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
- Step 2 - Create the Geoset
- Step 3 - Check the POI list
- Step 4 - Associate a Geoset ID to a Campaign
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.
Comments
0 comments
Please sign in to leave a comment.