Get Started with Glispa Connect

Overview

Examples

Android

Overview

- Native Ads

List/Feed

Custom

- Standard IAB Formats

Banner

Interstitial

Video

- Others

GDPR

Troubleshooting

Admob Android Adapter

Mopub Android Adapter

DFP Android Adapter

iOS

Overview

- Native Ads

List/Feed

Custom

- Standard IAB Formats

Banner

Interstitial

Video

- Others

GDPR

Troubleshooting

- Adapters

Admob iOS Adapter

Mopub iOS Adapter

DFP iOS Adapter

API Documentation

Reporting API

Help

GDPR FAQ

General

Earnings

Payments and Accounting

Integration

Reporting

Legal and Privacy

Updates

SDK Deprecation Schedule

SDK Change Log

Android Change Log

iOS Change Log

S2S API

Intro

This document serves as a guide and documentation for the server to server (known as S2S) integration with Glispa Connect ad exchange.

Conventions

The keywords “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

Prerequisites

You should register for a glispa Connect account here in order to get your Publisher id so you can use it later in the integration.

You can find your publisher id by going to APIs as seen here:

Ad lifecycle

  1. Ad request Client MUST ​request one or more ads from the Glispa Connect Adserver.
  2. Ad response The Ad Server MAY ​respond with one or more ads.
  3. Impression If the ad is shown to a user AND ​satisfies the viewability conditions then an impression MUST ​be tracked in real time.
  4. Click If the user click on the ad, then the ad’s url MUST ​be opened and the click MUST tracked in real time.

Ad request

Integrations start with an Ad request to Glispa Connect exchange. There are 2 environments:

  • Sandbox. A testing environment that MUST​ be used during development. This environment MUST not be used by the application released to the users.
  • Production. An environment that MAY ​be used once the implementation is completed for quality assurance purposes and MUST ​be used by the Application released to the users.

The protocol used for across environments MUST​ be HTTP 1.1 and http method MUST ​be

POST. Following the endpoint for each environment mentioned above:

Environment

Endpoint

Sandbox

<WILL BE PROVIDED FROM YOUR ACCOUNT MANAGER>

Production

<WILL BE PROVIDED FROM YOUR ACCOUNT MANAGER>

All requests MUST ​contain the following headers with the corresponding values:

  • Content­Type that MUST ​be set to application/json; charset=UTF­8
  • User­Agent, that MUST​ be your user agent details. (wikipedia)
All responses are of Content­-Type: application/json; charset=utf­8 and no other type is supported.
The sandbox environment is only for testing purposes by your development team. All the ads that are served through this endpoint are test ads with no real content and are not in any means chargeable (NO REVENUE IS TRACKED). You CANNOT use this endpoint in your production systems.

Body

The request body MUST ​be a valid json formatted string with the following four root elements:

Attribute

Type

Requirement

Description

app

App Object

REQUIRED

Details about the publisher’s app (i.e., non­-browser applications).

adunit

Ad Unit Object

REQUIRED

Details about the placement (ad unit) of the app.

device

Device Object

REQUIRED

Details about the user’s device to which the impression will be delivered.

user

User Object

RECOMMENDED

Details about the human user of the device; the advertising audience.

auctionSettings

Auction Settings Object

REQUIRED

Settings about the auction that will take place for this request

Below there is a detailed documentation on how each element is structured.
App Object

This object describes the app in which the ad will be displayed.

Attribute

Type

Requirement

Description

name

String

RECOMMENDED

The name of the app as specified in your network

id

String

REQUIRED

App id as specified in your platform

cat

Array, Category Object

RECOMMENDED

Array of categories of the app,

storeurl

String

RECOMMENDED

The app store url (e.g "https://itunes.apple.com/id628677149")

bundle

String

REQUIRED

A platform­ specific application identifier intended to be unique to the app and independent of the exchange.

*For iOS make sure that you pass the app store id (i.e 1122333445) instead of package name.

version

String

RECOMMENDED

Application version.

publisher

Publisher Object

REQUIRED

Publisher related properties

Category Object

This object describes the category of the app

Attribute

Type

Requirement

Description

id

String

REQUIRED

App Category id, Refer to https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf List 5.1 for a complete list of values that are applicable.

Publisher Object

This object describes the publisher

Attribute

Type

Requirement

Description

id

String

REQUIRED

This is your publisher id that you fetch from the publisher dashboard after your registration to our platform or from your account manager.

Ad Unit Object

This object describes an ad placement.

Attribute

Type

Requirement

Description

id

String

REQUIRED

Ad unit id as specified in your platform

name

String

RECOMMENDED

Ad unit human friendly name

type

String

REQUIRED

Adunit type

Available options:

  • NATIVE
  • BANNER

interstitial

Boolean

RECOMMENDED

Flag that defines if request is for Interstitial or not. Default is False

height

Integer

REQUIRED

Height of the ad placement

width

Integer

REQUIRED

Width of the ad placement

slots

Integer

OPTIONAL

Number of ads requested, default: 1.

Device Object

This object provides information pertaining to the device through which the user is

interacting. Device information includes its hardware, platform, location, and carrier data.

Attribute

Type

Requirement

Description

lmt

Boolean

REQUIRED

“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where false = tracking is unrestricted, true = tracking must be limited per commercial guidelines.

ifa

String

RECOMMENDED

ID sanctioned for advertiser use in the clear (i.e., not hashed).

geo

Geo Object

RECOMMENDED

Location of the device assumed to be the user’s current location.

devicetype

Integer

OPTIONAL

The general type of device (We use the exact format OpenRTB uses for this field).

language

String

OPTIONAL

Device language using

ISO-­639-­1-­alpha­2.

make

String

OPTIONAL

Device make (e.g., “Apple”).

model

String

OPTIONAL

Device model (e.g., “iPhone”).

os

Enumeration

REQUIRED

Device operating system, where available options (case­-sensitive):

  • “Android”
  • “iOS”

osv

String

REQUIRED

Device operating system version (e.g., “3.1.2”).

width

Integer

OPTIONAL

Physical width of the screen in pixels.

height

Integer

OPTIONAL

Physical height of the screen in pixels.

orientation

Enumeration

OPTIONAL

Current screen orientation. Available options:

  • "PORTRAIT"
  • "LANDSCAPE"
  • "UNDEFINED"

connection

Connection Object

REQUIRED

Details for device’s network connection.

carrier

Carrier Object

RECOMMENDED

Details for network connection carrier or ISP.

Connection Object

Attribute

Type

Requirement

Description

type

Integer

OPTIONAL

Type of network the device is using.

See Connection Type List 5.18 in for available values:

https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf

network

Integer

OPTIONAL

More specific definition of network.

See Connection Network options for available values.

Value

Network Type

0

UNKNOWN

1

GPRS

2

EDGE

3

UMTS

4

CDMA

5

EVDO_0

6

EVDO_A

7

1xRTT

8

HSDPA

9

HSUPA

10

HSPA

11

IDEN

12

EVDO_B

13

LTE

14

EHRPD

15

HSPAP

ip

String

REQUIRED

IPv4 of user’s device. This MUST ​be the user’s device current ip.

ua

String

REQUIRED

User Agent used from device.

Carrier Object

Attribute

Type

Requirement

Description

name

String

OPTIONAL

Network operator name.

operator

Operator Object

RECOMMENDED

Operator details.

Operator Object

Attribute

Type

Requirement

Description

mcc

String

RECOMMENDED

Mobile country code, of the provider of the SIM. (wikipedia)

mnc

String

RECOMMENDED

Mobile network code, of the provider of the SIM. (wikipedia)

iso

String

RECOMMENDED

ISO 3166­-1 alpha­-2 country code equivalent for the SIM provider's

country code. Example in Android TelephonyManager

User Object

This object contains information known or derived from the human user of the device (i.e., the audience for advertising).

Attribute

Type

Requirement

Description

yob

Integer

OPTIONAL

Year of birth as a 4­digit integer.

gender

Enumeration

OPTIONAL

Gender, where:

● “M” = male

● “F” = female

● “O” = known to be other

(i.e., omitted is unknown).

keywords

String

OPTIONAL

Comma separated list of keywords,interests, or intent.

geo

Geo Object

OPTIONAL

Location of the user’s home base defined by a Geo object. This MAY ​not necessarily be their current location.

hasConsent

String

OPTIONAL

GDPR related. If the user has given or not consent to store,process and transmit PII. Accepted values: “TRUE” , “FALSE”

Geo Object

Attribute

Type

Requirement

Description

lat

Float

REQUIRED

Latitude from ­90.0 to +90.0, where negative is south.

lon

Float

REQUIRED

Longitude from ­180.0 to +180.0, where negative is west.

Auction Settings Object

Attribute

Type

Requirement

Description

bcat

Array, String

OPTIONAL

Array of blocked ad categories that the user has asked not to display on the app, (default = [])
Refer to https://www.iab.com/wp-content/uploads/2015/05/OpenRTB_API_Specification_Version_2_3_1.pdf List 5.1 for a complete list of values that are applicable.

badv

Array, String

OPTIONAL

Array of blocked adomain that the user has asked not to display on the app (default = []) (e.g “ford.com”)

bidFloor

Float

OPTIONAL

Minimum valid bid price that the user has set for this ad request

secure

Boolean

OPTIONAL

Flag to indicate if the impression requires secure HTTPS URL creative assets and markup

Ad Response

Glispa Connect API respects the http protocol status code scheme in responses. Some of the most common status codes along with their descriptions are listed below:

Code

Message

Description

200

OK

204

No Content

400

Bad Request

401

Unauthorized

The application key is not properly authenticated. Either the access token was not sent or the token has expired.

500

Internal

Server Error

An unexpected error occurred on the server­side.

Body

Below are the top level attributes of the response JSON body.

Attribute

Type

Description

id

String

Unique id of the ad request.

ads

Array <Ad Object>

Array of Ads requested.

Ad Object

Attribute

Type

Description

id

String

Unique id of the ad.

type

String

  • BANNER
  • NATIVE

link

String

Ad landing url. Must be opened when user engages with that ad displayed.

*Only for Native type ads - Not applicable for Banner type ads

adm

For Native:
Adm Object

For Banner:
String

Creative payload of ad

For Native:
see Adm object

For Banner:
html payload

trackers



Array <Tracker Object>

Array of trackers that must be triggered per corresponding event.

It contains the impression and click trackers that MUST​ be triggered per corresponding event and it MAY ​have more than one per type.

*Only for Banner type ads - Not applicable to Native type ads

ad_choices

Ad Choices Object

Details about Ad Choices icon.

*Only for Native type ads - Not applicable for Banner type ads

price

Float

Clear price of winning bid

cid

String

Campaign id, used for debugging

Adm Object

Attribute

Type

Description

link

String

Ad

assets

Array <Asset Object>

Array of 1 or more assets that construct the ad

trackers

Array <Tracker Object>

Array of trackers that must be triggered per corresponding event.

It contains the impression and click trackers that MUST​ be triggered per corresponding event and it MAY ​have more than one per type.

*Only for Native type ads - Not applicable for Banner type ads

Asset Object

The actual assets returned in ad is dependent on the ad unit type of the ad unit id provided in ad request.

Attribute

Type

Description

type

String

Type of the asset. Available asset types are:

● title

● description

● icon

● cta

● rating

● image

data

String; Float; Image Object

Asset Type

Data Type

title

String

description

String

cta

String

icon

Image

Object

image

Image

Object

rating

Float in

range of

0.0 to 5.0

Data of the asset.

Image Object

Attribute

Type

Description

url

String

Url where the image

resource MUST​be retrieved

from.

width

Integer

Image width

height

Integer

Image height

Tracker Object

Attribute

Type

Description

type

String

Type of the tracker. Available options:

● impression

● click

url

String

Url to be triggered for tracking.

All tracker calls MUST ​be triggered using HTTP 1.1 protocol with method GET to the url provided.
Tracker url MUST NOT ​be altered in anyway, under no circumstances and MUST​ be used as provided.

Examples

Ad Request


{
"app": {
"name": "Drag Racing",
"id": "00000000-0000-0000-0000-000000000000",
"cat": [],
"storeurl": "https://play.google.com/store/apps/details?id=com.creativemobile",
"bundle": "com.example.test",
"version": "0.0.1-TEST",
"publisher": {
"id": "b1fc334d-e24d-11e6-be71-0e849cdcb6eb"
}
},
"adunit": {
"id": "32691ca1-a17e-4a10-ae3e-1efdc6d6db09",
"slots": 1,
"type": "BANNER",
"width": "300",
"height": "250",
"interstitial": false
},
"device": {
"lmt": false,
"ifa": "00000001-0002-0003-0004-000000f00005",
"geo": {},
"language": "ru-ru",
"make": "Google",
"model": "Nexus",
"os": "Android",
"osv": "4.2",
"width": 2560,
"height": 1600,
"orientation": "LANDSCAPE",
"connection": {
"type": 3,
"ip": "213.180.193.3",
"ua": "Mozilla/5.0 (Linux; U; Android 4.2; ru-ru; Nexus 10 Build/JOP12D) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Safari/534.30"
},
"carrier": {
"operator": {
"mcc": 204,
"mnc": 23
}
}
},
"auctionSettings": {
"bcat": ["IAB434"],
"bidFloor": 0.53,
"secure": false
},
"user": {
"id": "00000001-0002-0003-0004-000000000005",
"yob": 1990,
"gender": "M",
"keywords": "",
"hasConsent": false
}
}

Ad Response

Native

{
   "id": "715c7a2d-429f-4dd5-8b26-1cd2987e21c6",
   "ads": [
       {
           "id": "0",
           "type": "NATIVE",
           "adm": {
               "link": "https://www.glispa.com/connect/",
               "assets": [
                   {
                       "type": "title",
                       "data": "Sample Native Ad"
                   },
                   {
                       "type": "description",
                       "data": "Description for sample Native Ad"
                   },
                   {
                       "type": "cta",
                       "data": "Learn More"
                   },
                   {
                       "type": "rating",
                       "data": "4.5"
                   },
                   {
                       "type": "icon",
                       "data": {
                           "url": "https://s3.amazonaws.com/avocarrot-assets/media/images/ads/sample/120x120.jpg",
                           "width": 120,
                           "height": 120
                       }
                   },
                   {
                       "type": "image",
                       "data": {
                           "url": "https://s3.amazonaws.com/avocarrot-assets/media/images/ads/sample/300x250.jpg",
                           "width": 300,
                           "height": 250
                       }
                   }
               ],
"trackers": [],
               "ad_choices": {
                   "link": "https://www.glispa.com/privacy-policy/",
                   "assets": [
                       {
                           "type": "icon",
                           "data": {
                               "url": "https://s3.amazonaws.com/avocarrot-assets/media/images/ads/adchoices.png",
                               "width": "68",
                               "height": "68"
                           }
                       }
                   ]
               }
           },
           "price": 0.42,
"cid": "campaing id"
       }
   ]
}

Banner

{
   "id": "183a0294-ff0f-4930-b048-45192be0a78f",
   "ads": [
       {
           "id": "0",
           "type": "BANNER",
           "trackers": [
               {
                   "type": "click",
                   "url": "https://www.glispa.com/connect/"
               }
           ],
           "adm": "<html><head><meta charset=\"UTF-8\"><style>body{margin:0px;}</style></head><body><div style=\"position: relative\"><div style=\"background-position: top left; z-index: 99999; position: absolute;\"><a href=\"https://www.glispa.com/privacy-policy\"><img src=\"https://s3.amazonaws.com/avocarrot-assets/media/images/ads/adchoices.png\" alt=\" \" width=\"24vw\" height=\"24vw\"/></a></div></div><div><style type=text/css>body {margin:0px;}</style><a href=\"https://github.com/avocarrot\" target=\"_blank\"><img style='display: inline; min-width: 25vw; min-height: 25vh; max-width: 100vw; max-height:100vh;' src=\"https://s3.amazonaws.com/avocarrot-assets/media/images/ads/sample/300x250.jpg\" border=\"0\"/></a></div></body></html>",
           "price": 0.42,
"cid": "campaign_id"
       }
   ]
}

Tracking

Viewability conditions

For an impression to be considered valid and tracked, the ad must be visible for at least 50% in body​ and for more than 1 second.​

Impression tracking MUST ​be triggered in real time and ONLY i​f the ad is visible to the user (human that ad is displayed to) and satisfies the viewability conditions as mentioned above. The programmatic buyers are paying only when their impressions are tracked in real time.


Real time tracking MUST ​be triggered immediately after user action and in a frame of 30 minutes after the ad has been served (see Ad lifecycle & caching). Late impressions (tracked after 30 minutes) are discarded and not paid.

The above guidelines MUST​ be respected in order to be aligned with the IAB viewability terms.

Click tracking

Click tracking MUST​ be triggered in real time and ONLY i​f it is a result of a user’s auction (human that ad is displayed to).

Real time tracking MUST ​be triggered immediately after user action.

Caching

According to the Glispa Connect caching guidelines, you are only allowed to cache an ad for a maximum of 30 minutes​ after the Ad response and before and the impression is to be made.

Lifecycle of an ad starts with an Ad request to the Glispa Connect Adserver and MAY ​end with an Impression tracking that MAY​ be followed by a Click tracking event. Impression tracking MUST​ precede a Click tracking event.

Assets and trackers of an ad MAY ​be cached for 30 minutes but are valid for ONLY ​one impression tracking event and one click event. After the first impression/click is tracked the ad is invalid and client MUST​ trigger a new Ad request.

Support and More Info

For more info and support contact support.connect@glispa.com.


Was this article useful?