Mobile HTTP API

Salesforce Audience Studio allows website operators to create a holistic databank to organize, taxonomize, and make the full range of audience information actionable. It allows them to model, define and manage audience segments to improve content delivery and advertising revenue.

Audience Studio is now available to capture data and create audience profiles for mobile and OTT apps. This document is intended to describe details of the HTTP API that can be used by the app developers to send and receive data from Audience Studio.

If you want to use our iOS or Android SDK for mobile app data collection, please contact your Salesforce Audience Studio Account Manager.

Before you start

Before you start sending or receiving data from your apps, it is important to understand the number of requests that we will receive from your app.

Based off that information, we are going to send you the following:

  • Pixel URL: This URL is used to track views in your app. Please contact your Salesforce Audience Studio Representative to get this URL.
  • Event URL:  If you have created events in Audience Studio, you can call this pixel to send data for these events. Please contact your Salesforce Audience Studio Representative to get this URL.
  • Transaction URL:  This pixel is used to track transactions in your app. Please contact your Salesforce Audience Studio Representative to get this URL.

Note: The maximum request URL length is 4,000 characters.

Tracking of Views and sending parameters

This method is used to send view data from your apps to the Audience Studio backend server.

All these calls should be made asynchronously and should not impact the latency and stability of the core mobile app. All data should also be sent via a queuing approach to ensure that the calls are queued up when user is not connected to the internet.

Tracking of Views helps app developers to send data based on the actions users are performing on their apps.

Audience Studio SDK performs all the above tasks asynchronously and sent via a queuing approach.

Note: If pixel is being built using server-side call the client IP will need to be passed into the request header X-Forwarded-For

To send data to Audience Studio servers for views, you will need the following:

Attribute Name

Value

Pixel URL

URL provided by Salesforce  Audience Studio representative to send view data.

_kpid

Publisher uuid.

Please contact Salesforce Audience Studio Representative to get the publisher uuid.

_kcp_d

Domain.

You can use the domain of your web site for this value.

_kcp_s

Site Name.

Name of the Control Tag as per Manage Sites.

_kcp_sc

Section. This is the section of the app that you want to send data for.

For e.g., this could be “open_app” or “home_page”.

Also, the value for this attribute should be url encoded.

 

_kuid

Unique device ID to track the user.

For iOS, this should be the unique Advertiser Id (and not the device id)

For OTT, you must pass each device ID in a prefix format.  This is because activation partners that accept OTT devices need them broken out to know which devices the users came from (currently we only push OTT devices to FreeWheel).

These are the current OTT prefix formats we accept:

ott:rida:<OTTID> for Roku
ott:aaid:<OTTID> for Android TV
ott:idfa:<OTTID> for Apple TV
ott:afai:<OTTID> for Amazon Fire
ott:msai:<OTTID> for Microsoft

<OTTID> should be replaced with the OTT device ID of the user.

NOTE: The colons in the OTT prefix must stay as is - please do not encode them when sending to our pixels.

_kpa_<page_attribute_name>

All the page attribute data that needs to be sent should be prefixed with _kpa_ prefix.

PLEASE NOTE: If you wish to pass more than one attribute value to a single attribute in the pixel call, please make sure the values are comma-separated when passing them.

_kua_<user_attribute_name>

All the user attribute data that needs to be sent should be prefixed with _kua_ prefix.

PLEASE NOTE: If you wish to pass more than one attribute value to a single attribute in the pixel call, please make sure the values are comma-separated when passing them.

tech_browser

If the user-agent isn't being passed into the header of the request to make the pixel call tech_ attributes will need to be passed to supplement for the user-agent

tech_browser_lang If the user-agent isn't being passed into the header of the request to make the pixel call tech_ attributes will need to be passed to supplement for the user-agent
tech_manufacturer If the user-agent isn't being passed into the header of the request to make the pixel call tech_ attributes will need to be passed to supplement for the user-agent
tech_os If the user-agent isn't being passed into the header of the request to make the pixel call tech_ attributes will need to be passed to supplement for the user-agent

A request to the pixel URL returns a 204 No Content Response.  An example of the Pixel URL might look like the following if it were for an iOS app:

CLICK TO SCROLL and view entire tag

https://beacon.krxd.net/pixel.gif?tech_browser_lang=en&_kpid=<publsher_uuid>&_kcp_d=<domain>&_kcp_s=<site>&_kcp_sc=<section>&_kpa_<name>=<data>&_kua_<name>=<data>&_kuid=<IDFA_OR_AAID>

 For a pixel.gif call being used in a Roku app, it might look like this:

https://beacon.krxd.net/pixel.gif?tech_browser_lang=en&_kpid=<publsher_uuid>&_kcp_d=<domain>&_kcp_s=<site>&_kcp_sc=<section>&_kpa_<name>=<data>&_kua_<name>=<data>&_kuid=ott:rida:<OTTID>

 

Tracking of events and their attributes

For Tracking events, you will need the following:

Attribute Name

Value

Event URL

Event URL is created in the Audience Studio UI under: https://console.krux.com/events/list

Make sure there is an "event_id" passing to this event URL when you generate this event tag - otherwise, we will not be able to associate the data to the proper event in the UI

_kuid

Unique User Id to track the user.

For iOS, this should be the unique Advertiser Id (and not the device id)

For OTT, you must pass each device ID in a prefix format.  This is because activation partners that accept OTT devices need them broken out to know which devices the users came from (currently we only push OTT devices to FreeWheel).

These are the current OTT prefix formats we accept:

ott:rida:<OTTID> for Roku
ott:aaid:<OTTID> for Android TV
ott:idfa:<OTTID> for Apple TV
ott:afai:<OTTID> for Amazon Fire
ott:msai:<OTTID> for Microsoft

<OTTID> should be replaced with the OTT device ID of the user.

NOTE: The colons in the OTT prefix must stay as is - please do not encode them when sending to our pixels.

<event attributes>

Event attributes along with their values. This will be different for different events and based off which attributes have been created for the event.

PLEASE NOTE: If you wish to pass more than one attribute value to a single attribute in the pixel call, please make sure the values are comma-separated when passing them.

A request to the event URL returns a 204 No Content Response.

An example event request URL would look like the following:

CLICK TO SCROLL and view entire tag

https://beacon.krxd.net/event.gif?event_id=LnQCYq9Q&event_type=ad&testAttribute1=testValue1&testAttribute2=testvalue2&_kuid=<AAID or IDFA>

 And this would be an example event request URL in a Roku app:

https://beacon.krxd.net/event.gif?event_id=LnQCYq9Q&event_type=ad&testAttribute1=testValue1&testAttribute2=testvalue2&_kuid=ott:rida:<OTTID>

 

Tracking of transactions and their attributes

For Tracking transactions, you will need the following:

Attribute Name

Value

Data Type

Required?

Transaction URL

URL provided by Salesforce Audience Studio representative to send transactional data.

String

Yes

_kpid

Publisher uuid.

Please contact Salesforce Audience Studio Representative to get the publisher uuid.

String

Yes

_kuid

Unique User Id to track the user.

For iOS, this should be the unique Advertiser Id (and not the device id)

For OTT, you must pass each device ID in a prefix format.  This is because activation partners that accept OTT devices need them broken out to know which devices the users came from (currently we only push OTT devices to FreeWheel).

These are the current OTT prefix formats we accept:

ott:rida:<OTTID> for Roku
ott:aaid:<OTTID> for Android TV
ott:idfa:<OTTID> for Apple TV
ott:afai:<OTTID> for Amazon Fire
ott:msai:<OTTID> for Microsoft

<OTTID> should be replaced with the OTT device ID of the user.

NOTE: The colons in the OTT prefix must stay as is - please do not encode them when sending to our pixels.

String

Yes

quantity

The total quantity of the products purchased in the order.

Integer

Yes

price

The total order amount. 

Float

Yes

date

The transaction date

Date (yyyy-mm-dd format)

Yes

<transaction attributes>

Any additional order attributes you'd like to track (e.g. productName, productSKU) 

PLEASE NOTE: If you wish to pass more than one attribute value to a single attribute in the pixel call, please make sure the values are comma-separated when passing them.

String

No

A request to the transaction URL returns a 204 No Content Response. 

An example of the transaction URL in a mobile app might look like the following:

CLICK TO SCROLL and view entire tag

https://beacon.krxd.net/transaction.gif?_kpid=<publsher_uuid&quantity=2&price=43.5&date=2017-05-01&product_sku=123456&payment_method=paypal_kuid=<IDFA_OR_AAID>

 

An example of the transaction URL in a Roku app might look like the following:

CLICK TO SCROLL and view entire tag

https://beacon.krxd.net/transaction.gif?_kpid=<publsher_uuid&quantity=2&price=43.5&date=2017-05-01&product_sku=123456&payment_method=paypal_kuid=ott:rida:<OTTID>

 

Have more questions? Submit a request

0 Comments

Article is closed for comments.