API - Developer Guide
Cuebiq Support Team
  • Updated
Follow

Campaigns are the overarching containers for all reports and pixels. Every campaign can be associated with multiple reports and each report is associated with a single pixel. This guide will walk through the steps to set up a new campaign and autofill data between your DSP and Cuebiq.

Table of Contents

Prerequisites

In order to create campaigns or to manage every single API call, you need a token and a refresh token. To get these tokens, you will need to request access to the API. Once access has been approved, Cuebiq will provide a client_id and client_secret as well as a customerId. A token will allow you to call every available endpoint in the Cuebiq API. Please refer to this article to find more details on the authentication process.

The flow described below reflects the order in which every campaign should be configured.

Setting up a Campaign

Create a Campaign

Overview

The campaign can be considered a container of every delivery related to your marketing campaign. If you run media through different channels or inventories, you can create as many reports as you want, measure single deliveries as report instances, and have a holistic view at the campaign level.

POST   /v2/customers/{customerId}/campaigns

See the endpoint documentation for more information and a sample request and response.

 

Campaign Parameters

Field

Required

Type

Description

name

yes

string

This is the name of your Measurement campaign 

vertical*

yes

string

This is the industry vertical of your campaign

flightDatesRange

yes

object

The object that includes the start and end date of your campaign (eg: {"start":"2022-01-01","end":"2022-01-31"})

conversionWindow

yes

integer

The number of days to assign as the conversion window

conversionIntervalRange**

yes

object

The object that includes the start and end date of the conversion interval

brand

optional

string

This is the brand name for which you run a campaign
externalRef optional string This is an arbitrary string that can contain custom info related to the campaign

 

*verticals available are QSR, RETAIL, TOURISM, OTHER

**eg: if you apply a conversion window of 7 days and the flight dates are from 2022-01-01 to 2022-01-31, setup the conversion interval as (eg: {"start":"2022-01-01","end":"2022-02-07"})

 

Create and associate a Geoset

Overview

A Geoset represents the group of POIs (ex. stores) where you want to measure the effectiveness of your campaign. Without this parameter, Cuebiq can't measure properly the visits that happen within your stores. The Geosets are associated with every single campaign and they're unique for each report you configure inside your campaign.

 

Create a Geoset

The most efficient flow in order to create a Geoset and associate it to the related campaign is the following one.

Step 1 - Create the AWS pre-signed URL

This step creates an Amazon S3 pre-signed URL where you can upload your Geoset file. A successful response from this endpoint will return a presignedUrl, an objectUrl, and an expiration date and time because the created URL has a limited validity time. Once the URLs are generated, copy the objectUrl and then upload your Geoset file.

Please read the documentation on how to upload a proper Geoset.

The steps to upload a Geoset file are many and they depend on your architecture or framework or your codebase. A very simple method is to make a PUT API call to the presignedUrl just generated and append into the body of the request the local path of the Gesoet file.

POST   /v1/customers/{customerId}/geosets/upload-urls

See the endpoint documentation for more information and a sample request and response.

 

 

Step 2 - Create the Geoset

This step creates a Geoset and links that to the previously uploaded Geoset file. A successful response from this endpoint will return the geosetId you will have to use in Step 3.

POST   /v1/customers/{customerId}/geosets

See the endpoint documentation for more information and a sample request and response.

 

Geoset Parameters

Field

Required

Type

Description

name*

yes

string

The name you want to associate with your Geoset (3-64 characters)

placeDwellTimeMinutes

yes

object

The object that contains the dwell time of your store list. The dwell time is the time interval you want to consider as a visit 

placeOpeningHours

yes

object

The object that contains the opening hours, per day, of your stores' list. Please use the standard 24-hour clock format

placeRadiusMeters

yes

number

The radius of the geoset in meters

externalRef

optional

string

This is an arbitrary string that can contain custom info related to the geoset

placesFileLocation

yes

string

The objectUrl obtained from Step 1

* This is a configuration example

{
    "name": "Geoset Name",
    "placeDwellTimeMinutes": { "first": 5, "second": 150 },
    "placeOpeningHours": {
      "mon": [ { "from": "09:00", "to": "18:00" } ],
      "tue": [ { "from": "09:00", "to": "18:00" } ],
      "wed": [ { "from": "09:00", "to": "18:00" } ],
      "thu": [ { "from": "09:00", "to": "18:00" } ],
      "fri": [ { "from": "09:00", "to": "18:00" } ],
      "sat": [ { "from": "09:00", "to": "18:00" } ],
      "sun": [ { "from": "09:00", "to": "18:00" } ]
    },
    "placeRadiusMeters": 30,
    "placesFileLocation": "https://example.com"
}

 

 

Step 3 - Check the POI list

This step retrieves the list of POIs with their addresses and geographical coordinates. Please check it before associating it with a report.

GET  /v1/customers/{customerId}/geosets/{geosetId}/places

See the endpoint documentation for more information and a sample response.

 

 

Step 4 - Associate a Geoset ID to a Campaign

This step associates the Geoset ID created in Step 2 with a campaign.

PUT  /v2/customers/{customerId}/campaigns/{campaignId}/geoset

See the endpoint documentation for more information and a sample request and response.

 

Field

Required

Type

Description

geosetId

required

string

The Geoset ID generated after a successful response in Step 2

 

Create a Report

Overview

The report is the single instance of measurement and it's strictly related to your media and your channels. Cuebiq supports different media types and channels. 

Note: The report will automatically adopt the flight dates of the campaign and each report can have no more than 1 pixel assigned.

POST   /v2/customers/{customerId}/campaigns/{campaignId}/reports

See the endpoint documentation for more information and a sample request and response.

 

Report Parameters

Field

Required

Type

Description

name

yes

string

The name of the report

estimatedImpressions

optional

integer

The number of estimated impressions for this report

cpm

optional

number

The cpm for this report

totalBudget

optional

number

The total budget for the report. If you want to obtain KPIs such as the cost per visit, this is required
externalRef optional string This is an arbitrary string that can contain custom info related to the report

inAppOnly*

yes

boolean

Specification of the type of media being served.
deliveryHTTP**

yes

boolean

Put default as false
deliveryHTTPPostbackURL
 optional string Add Postback URL if applicable
deliveryHTTPAuthToken
 optional  string Add authentication token if applicable
deliveryS3
 yes boolean Put default as false
deliveryUI
 yes boolean Put default as false

*media type supported: 1 for In-App only, 0 for Mixed Digital Deliveries ( Cross-Device, CTV, In-App )

** reach out to your dedicated AM in order to understand this additional capability

 

Create and Associate a Digital Pixel to a Report

Overview

In order to receive and measure data coming from display impressions, a pixel is required. Those pixels are placed into DSPs platforms and when a user event happens, Cuebiq is able to receive that impression. Cuebiq partners with an extended list of DSPs that natively support proprietary parameters. Cuebiq will manage the database of this ecosystem in order to facilitate your pixel setup, based on your proprietary fields. You can retrieve the full list of supported DSPs and their parameters by making this request:

GET   /v2/dsp/

This is a sample of a response. In the macros array, you can find the pixel parameters you have to configure when you are going to create a pixel.

"items": [ 
{ "id": "c2764d27-fc5c-4387-ad9a-30df885d542321", 
  "name": "DSP NAME", 
  "description": "", 
  "macros": [ 
     { 
      "dspId": "c2764d27-fc5c-4387-ad9a-30df885d542321", 
      "name": "Device Id", 
      "macro": "${TM_USER_ID}", 
      "pixelParameter": "deviceId", 
      "description": null 
     }, 
     { 
      "dspId": "c2764d27-fc5c-4387-ad9a-30df885d542321", 
      "name": "Placement Id", 
      "macro": "${TM_PLACEMENT_ID}", 
      "pixelParameter": "placementId", 
      "description": null 
     } 
   ] 
} 
]

 

It is possible also to get specific DSP information and parameters using the DSP Id by calling the following specific endpoint.

GET   /v2/dsp/{dspId}

 

 

Create a Pixel

Once you get your DSP ID and you already know your proprietary parameters, you can create your own pixel, build your own custom creativities and add different permutations. The permutations are the different cardinalities in terms of creativities that your campaign has, based on the parameters and the audience of your campaign. In order to associate the pixel to a report, you need a valid campaignId and reportId.

POST   /v2/customers/{customerId}/campaigns/{campaignId}/reports/{reportId}/pixels

 

Pixel Parameters

Field

Required

Type

Description

dspId

yes

string

The ID of your DSP

deviceId

yes

string

The proprietary value to detect a device ID

impressionId

optional

number

The id of every single impression

latitude

yes

string

The proprietary values to detect the approximated latitude of an impression

longitude

yes

string

The proprietary values to detect the approximated longitude of an impression
creativeName

optional

string

Custom generic pixel parameter
creativeType optional string Custom generic pixel parameter
publisherId optional  string Custom generic pixel parameter
placementId optional string Custom generic pixel parameter
permutations*
 optional array of strings See below

* This is a permutations example

"permutations": [ 
{ "SID1": "NETFLIX", "SID2": "Male15/25" }, 
{ "SID1": "DISNEYPLUS", "SID2": "Male15/25" },
{ "SID1": "NETFLIX", "SID2": "Female15/25" }, 
{ "SID1": "DISNEYPLUS", "SID2": "Female15/25" },
{ "SID1": "NETFLIX", "SID2": "NoAnswer15/25" }, 
{ "SID1": "DISNEYPLUS", "SID2": "NoAnswer15/25" }
]

 

 

Extract Measurement KPIs

Once you have created a campaign with a report and pixel and have started to deliver impressions, you can begin to extract Measurement KPIs. 

Note: Not all KPIs will be available from the first day of a campaign. Metrics like uplift and incremental visits require enough visits to achieve statistical significance before appearing and this can take time.

 

Prerequisites 

In order to create campaigns, you need a token and refresh token request as described in the first paragraph. You also need a valid campaignId and reportId to proceed.

 

Available KPIs

Most measurement KPIs are available at the campaign and report levels. While most metrics are available daily, several metrics are available in cumulative form (ex. Dwell time). 

Note: Make sure that you are referencing the intended metric format when incorporating this data into your own reports.

 

Campaign Level Metrics

These metrics are based on aggregated and de-deduped data for the campaign.

See the endpoint documentation for more information and a sample response.

 

Metric

Form

Description

Impressions

Daily

Total impressions of all reports

Measured people

Daily

People within Cuebiq’s universe that received impressions - total and de-duped from the reports

Measured visits

Daily

People within Cuebiq’s universe that visited - total and de-duped from the reports

Projected visits

Daily

A projection of the total number of visits, even outside Cuebiq’s universe based on POI, the volume of impressions visit rate, etc.  

Reached people

Daily

A projection of the total number of people reached by the campaign, even outside Cuebiq’s universe, based on POI, the volume of impressions, etc. 

Uplift

Daily

Comparison % of the visit rates between the exposed and control groups

Incremental visits

Daily

Additional visits that occurred post-exposure that were outside a person’s normal visitation behavior

Visit rate

Daily

Unique Measured Visitors / Measured people

 

Report Level Metrics

These metrics are based on aggregated and de-deduped data for the report.

See the endpoint documentation for more information and a sample response.

 

Metric

Form

Description

Dwell time

Cumulative

Time, in minutes, visitors spent in-store

Impressions

Daily

Impressions delivered on the pixel associated with a report

Measured people

Daily

People within Cuebiq’s universe that received impressions

Measured visits

Daily

People within Cuebiq’s universe that visited after being exposed

Projected visits

Daily

A projection of the total number of visits, even outside Cuebiq’s universe based on POI, the volume of impressions visit rate, etc.  

Reached people

Daily

A projection of the total number of people reached by the campaign, even outside Cuebiq’s universe, based on POI, the volume of impressions, etc. 

Uplift

Daily

Comparison % of the visit rates between the exposed and control groups

Incremental visits

Daily

Incremental visits for the report

Visit rate

Daily

Unique Measured Visitors / Measured people

 

Shared Campaigns and Report Metrics

The same metrics described in previous sections are now available also if you have a campaign or report shared with your organization.

See the endpoint documentation for more information and sample requests and responses.

 

Extract KPIs at Cut Level

Measurement KPIs at cut level are important metrics that demonstrate the performance of your campaign, per creativity. When you create a pixel or multiple permutations, you can obtain extremely important information per each cardinality, understanding which fraction of media is performing badly or well and especially how to optimize your targeting.

See the endpoint documentation for more information and sample requests and responses.

GET   /v2/customers/{customerId}/campaigns/{campaignId}/reports/{reportId}/pixels/kpi-analysis-by-cut

This is a sample of a response. Per each day, you can retrieve all the metrics available related to the parameter cardinality.

"items": [ 
{ 
   "runDate": "2022-01-25", 
    "impressions": 756851.0, 
    "measuredPeople": 15968, 
    "reachedPeople": 305707.3267719826, 
    "uplift": { 
       "value": 0.2740318835640825, 
       "lowerBound": 0.055842051149204375, 
       "upperBound": 0.5373106598389026, 
       "confidenceIndex": 0.9942473888813819 
    }, 
    "projectedIncrementalVisits": 415.9035077968364, 
    "visitRate": 0.0157189378757515, 
    "measuredVisits": 428.0, 
    "projectedVisits": 8194.405557866401, 
    "walkThroughRate": 0.010826973285186121, 
    "parameters": { "sid1": "SID1" } 
}, 
{ 
   "runDate": "2022-01-25", 
    "impressions": 756851.0, 
    "measuredPeople": 15968, 
    "reachedPeople": 305707.3267719826, 
    "uplift": { 
       "value": 0.2740318835640825, 
       "lowerBound": 0.055842051149204375, 
       "upperBound": 0.5373106598389026, 
       "confidenceIndex": 0.9942473888813819 
    }, 
    "projectedIncrementalVisits": 415.90350779683655, 
    "visitRate": 0.0157189378757515, 
    "measuredVisits": 428.0, 
    "projectedVisits": 8194.405557866401, 
    "walkThroughRate": 0.010826973285186121, 
    "parameters": { "sid2": "SID2" } 
}
]

 

Glossary

  • Campaign Name - Name assigned to a campaign Ex. Cuebiq_Fall_2020.
  • Brand - The advertising brand - Ex. McDonalds.
  • Vertical - The type of business - Ex. QSR, Retail, Tourism.
  • Flight Dates - The date range of the campaign.
  • Conversion window - The # of days after an impression is served that a visit will count. 
  • POI (point of interest) - Term used for describing a single store or location.
  • Geoset - A list of POIs that you want to measure foot traffic to.
  • Cross-Device - A type of report measuring digital media served on desktops, tablets, mobile web browsers, and even in-app. 
  • InApp - a type of report for pixels running only on in-app inventory.
  • Customer ID - an ID that identifies you as the client.
  • Campaign ID - an ID that identifies a single campaign.
  • Report ID - an ID that identifies a single report.

Related articles

Comments

0 comments

Please sign in to leave a comment.