Becoming an Audience Injection Partner

Audience injection is an automated method for creating and mapping audience objects between Oracle Data Cloud platform and execution platforms. With audience injection, the Oracle Data Cloud platform authenticates into your system and uses your APIs to create audience objects. Your APIs return your "external audience IDs" for the injected audience and the platform includes them in subsequent data so that you can add users to your audience objects.

Audience injection makes delivering and activating audiences between platforms a rapid, seamless, self-serve process for mutual clients and it eliminates the need for your team to manually map segment objects.

Audience injection workflow

Prerequisites

To become an audience injection partner, you must meet the following requirements:

• Audiences API: You must have a RESTful audience API that supports POST, GET, and PUT methods for creating, verifying, and updating audiences in your system and can successfully respond to a set of cURL commands.
• Data delivery: You must be able to receive Oracle Data Cloud platform data via server data transfer (SDT) or JSON return.
• Authentication: The platform must be able to authenticate into your system using one of the following methods:
  • OAuth 2.0 authorization code grant type
  • Access token with extended time to live (TTL)
Your authentication endpoints must adhere to the following syntax:
• https://your_authorization_provider_url.com/oauth2/authorize
• https://your_authorization_provider_url.com/oauth2/token

To develop your audience injection app:

1. Send your authentication and audience API documentation to your Oracle Data Cloud platform partner manager and set up a meeting to review your integration.
2. Validate your audience API with the provided cURL commands and send the results to your Oracle Data Cloud platform partner manager.
3. Create your audience injection app that includes your authorization service, audience services, and data delivery method and then save it for testing. The Oracle Data Cloud platform must validate your APIs in order for your app to be published. This is a requirement for engineering support to help debug and troubleshoot your app.
4. Test your app to verify the following:
   • Audiences are created in your system.
   • The platform receives and stores your external audience IDs.
   • Data delivery results in users being added to your external audiences.
5. (Recommended) Provide Oracle Data Cloud with a test seat in your system to test and validate the integration and help document how clients can find and use their audiences.
6. Work with Oracle Data Cloud to create instructions for your app. If you do not provide a test seat in your system, you will need to provide instructions and screenshots showing clients how to find their Oracle Data Cloud audiences in your system.
7. Beta test the integration with one to three clients for two to four weeks.
8. Publish the app to the Oracle Data Cloud app catalog, which makes your integration available to all clients.
9. The client adds your app to their DMP and is then re-directed to your provider URL where they enter their credentials for your system and grant access to Oracle Data Cloud for creating and updating audiences in their seat.
10. The client creates an audience and delivers it in the Oracle Data Cloud platform. The platform creates a campaign corresponding to the audience delivery.
    
11. The platform calls your audience creation API to inject the client's audience into their seat in your system.
12. The platform delivers the client's user data (unique user ID, external audience ID, categories, or campaign ID) to your system via SDT or JSON return.

App creation

During the app creation process, you provide all the information needed for the audience injection integration, including a name, description, logo, pricing models, and a data delivery method. The process and requirements are described in developing an app.

For audience injection apps, you must provide your:

• Injection method (direct or indirect)
• Authentication service
• Audience object JSON schema
• Audience API

Injection method

Select how Oracle Data Cloud audiences are passed into the client seat within your system:

• Direct injection: The Oracle Data Cloud platform creates the audience object directly in the client's seat within the app partner's platform.
• Indirect injection: The Oracle Data Cloud platform creates the audience object in the app partner's platform and then provisions the object based on the account identifier for your system provided by the client when they install your app. If you use indirect injection, you must provide us with a test advertiser ID, account ID, client ID, or other identifier that we can use to validate your indirect audience injection integration.

Authentication service

To allow the Oracle Data Cloud platform to create and edit the client's audiences object in their seat within your system and to add users to the lists, you must use the OAuth 2.0 protocol's authorization code grant type.

Note: The Oracle Data Cloud platform does not currently support the client credentials type or any other OAuth 2.0 method.

As an alternative to using OAuth 2.0, you can provide an access token with an extended TTL that can be used to inject audiences into all client seats or into a specific seat. your system must support HTTP authentication to use an access token.

Provide the following information:

Audience object JSON schema

You must specify the JSON schema of the audience object sent to your system and the name of the field used to pass the primary ID of the injected audience back to the platform. Your POST and PUT methods must both support this schema.

Default audience object schema:

{ "name": "$AUDIENCE_NAME_$CAMPAIGN_NAME_$TIMESTAMP", "price": $PRICE "advertiserId": $ADVERTISER_ID }

Fields in the standard JSON-formatted audience object you will receive from the platform:

You can include the following macros in your audience object input schema:

The following example shows how you can configure the JSON schema of the audience objects sent to your system.

Sample audience object (JSON) sent to vendor:

{
	"name": "Oracle Data Cloud platform Audience: $AUDIENCE_NAME",
	"price": $PRICE,
	"advertiserId": $ADVERTISER_ID
}

The following example shows how you can configure the audience object input schema.

Sample audience object (JSON) output:

{
	"external_audience_id":"123-abc-456",
	"name": "Vendor Campaign_BlueKai Audience_1432131627"
}

Audience object fields:

Audience Object ID Name

You need to provide the name of the key linked to the unique IDs generated for your audience objects created in your system (for example, external_audience_id, id, or segment_id). When the platform creates an audience object in your system (via a POST request to your Audience API), your API will return a JSON object with the ID created in your system for the audience (for example, "external_audience_id": "123").

Audience API

You need to provide Oracle Data Cloud with an Audience API for that supports POST, GET, and PUT methods for creating, verifying, and updating audience/segment objects in your system, respectively.

Audience creation (POST)

The POST method is needed to receive audience objects from the Oracle Data Cloud platform in JSON format, using the audience object JSON schema you specified. If your system accepts third-party data, your audience API must be able to accept the price field in the JSON body. When you receive the POST request, you will return the external audience created in your system back to the platform in JSON format.

Request

example.com/rest/audiences

Sample body

{
	"name": "Vendor Campaign_BlueKai Audience_1432131627",
	"price": 1.35,
	"advertiserId": 12345
}

Sample success response: HTTP 200 success code and the following JSON body

{
	"external_audience_id":"123-abc-456",
	"name": "Vendor Campaign_BlueKai Audience_1432131627"
}

Error response: HTTP 4xx error code. If the error is related to authorization, authentication, or an expired access token, you must return a 401 or 403 error. The Oracle Data Cloud platform does not currently parse or display the error code. Error codes are important for internal debugging.

Audience verification (GET)

The GET method is needed for Oracle Data Cloud to verify that an audience/segment object has been created in your system for an injected audience.

Request:

example.com/rest/audiences/externalAudienceID

Sample success response: HTTP 200 success code and the following JSON body:

{
	"external_audience_id":"123-abc-456",
	"name": "Vendor Campaign_BlueKai Audience_1432131627"
}

Error response: HTTP 4xx error code

Audience update (PUT)

If you are receiving third-party data, the PUT method is needed to support the updating of the CPM of an audience. This may occur if category prices change or the client changes the categories in their audience. The PUT request must support an external audience ID in the URL path.

Request:

example.com/rest/audiences/externalAudienceID

Sample body:

{
	"price": 1.00
}

Sample response: HTTP 200 success code and the following JSON body:

{
	"external_audience_id":"123-abc-456",
	"price": "1.00"
}

Error response: HTTP 4xx error code

The PUT method must support the same audience schema as the POST. The sample body demonstrates the typical PUT use case of updating just the price; however, your PUT method must be able to accept all of the same parameters as the POST.

Testing your audience API

You can use the following cURL commands to test your audience API before trying to create your audience injection app. You must provide a bearer access token and place it in the authorization header, and you must include your audience endpoint.

POST syntax:

curl -X POST -d'{"name": "audienceName","price": D.CC,"audience_id": "audienceID"}' -H'Content-Type:application/json' -H'Authorization: Bearer yourAccessToken' 'yourAudienceEndpoint'

POST example:

curl -X POST -d'{"name": "BK_AI JS test audience1","price": 1.75,"audience_id": "abc123"}' -H'Content-Type:application/json' -H'Authorization: Bearer atesttoken' 'http://www.mocky.io/v2/570d68b8120000c60412e589'

GET syntax

curl -X GET -H'Content-Type:application/json' -H'Authorization: Bearer yourAccessToken' 'yourAudienceEndpoint/audienceID'

GET example

curl -X GET -H'Content-Type:application/json' -H'Authorization: Bearer atesttoken' 'http://www.mocky.io/v2/570d68b8120000c60412e589/abc123'

PUT syntax

curl -X PUT -d'{"price": D.CC}' -H'Content-Type:application/json' -H'Authorization: Bearer yourAccessToken' 'yourAudienceEndpoint/audienceID'

PUT example

curl -X PUT -d'{"price": 1.50}' -H'Content-Type:application/json' -H'Authorization: Bearer atesttoken' 'http://www.mocky.io/v2/570d68b8120000c60412e589/abc123'

Audience creation and delivery

In the Oracle Data Cloud platform, the client creates an audience containing their first-party data, private second-party data shared with them by other clients, and third-party data purchased from the Oracle Data Marketplace. The client then delivers the audience to specify where to inject their audiences.

Audience injection

When the client's audience delivery becomes active, the platform calls your audience creation API with the access token obtained in the app creation step to inject the audience into the client's seat in your system. Your audience creation API returns your external audience ID back to the platform.

You need to provide Oracle Data Cloud with your audience creations APIs. When a campaign is activated, the platform calls your system's audience creation API with an access token and creates an audience object in the client's seat within your system. The audience is immediately available to clients for targeting.

Each app partner platform uses a slightly different hierarchy for storing audience objects. If audience objects are stored within a hierarchy in the vendor platform (e.g., at the advertiser level or campaign level), Oracle Data Cloud may need to know how to associate audience objects to the appropriate level within the vendor platform.

Data delivery

When delivering data via a standard delivery method, (SDT or JSON return), the platform will pass the list ID that maps the user or campaign to your segment object and the categories, and the platform for which the user qualified.

SDT

The SDT method transfers user data from the Oracle Data Cloud platform into your server-side profile store in our standard delivery format. Once an ID swapped has been won by a campaign, real-time data that includes the unique user ID (UUID) and external audience ID is delivered into your system via JSON-formatted POST requests. The external_audience_id is included as a separate key-value pair in the JSON object (and it is also appended to the PixelURL attribute). Alternatively, the platform can store the user data in hourly or daily batch files that you can download from the Oracle Data Cloud SFTP server or an Amazon S3 bucket. Based on the SDT data, you add the user to the specified list. The following example demonstrates the data that will be delivered into your system.

Example SDT JSON object:

{ 
   "DeliveryTime":"Thu Dec 22 02:22:33 PST 2016",
   "DestinationId":1,
   "PixelCount":1,
   "Pixels":[ 
      { 
         "BkUuid":"6tRenM19999/4qBn",
         "CampaignId":45671,
         "CategoryId":"17 ",
         "PartnerUuid":"YOUR_PARTNER_UUID",
         "PixelId":9151,
         "PixelUrl":"http://www.site.com/15415/pixel.gif?external_audience_id=123-abc-456",
         "Rank":4,
         "Timestamp":"Thu Dec 22 02:22:33 PST 2016",
         "UtcSeconds":1482445313,
         "external_audience_id":"123-abc-456"
      }
   ]
}  

JSON return

The JSON return delivery method transfers user data from the Oracle Data Cloud platform to a web page hosting a JavaScipt tag. When a qualifying user visits the page, the platform returns a bk_results object that contains JSON-formatted data including the external_audience_id and the categories for which the user qualified. The JSON return method is typically used by site optimization and dynamic creative optimization partners. The following example demonstrates the data that will be delivered into your system.

Example JSON return tag

var bk_results = {
    "campaigns": [
    {
        "campaign": 45671,
        "external_audience_id": "123-abc-456",
        "timestamp":1482445313,
        "categories": [
            {
                "categoryID":17,
                "timestamp":1482445842
            }
        ]
    }]
};

FAQs

What are the benefits audience injection?

Audience injection automates and expedites the audience mapping process, which provides the following benefits:

• Clients can self-serve their delivery of their audiences into your system, which makes working between platforms to activate their data a quick, seamless process. Audiences are typically fully ramped and ready for activation in your system within 24 hours because the mapping is done immediately. With a manual mapping process, it typically takes 48-72 hours for the clients' audiences to be ramped.
• The Oracle Data Cloud platform does not have to spend resources providing the information needed to map the client's audiences in your system. The time saved with audience injection can be invested in further enhancing the integration with, for example, analytics, insights, and other media campaign optimizations.
• You do not have to spend time on communication with Oracle Data Cloud and the client to get the information needed to map clients' audiences and you don't have spend resources doing the actual mapping itself. With a quick, easy integration, clients are more likely to deliver their data into your system.

What do I need to do an audience injection integration?

You need to provide an authentication method that Oracle Data Cloud can use to get access to client's seats in your system and an audience API that supports POST, GET, and PUT methods. You must also be able to receive user data from the Oracle Data Cloud platform via SDT or a JSON return tag.

My authentication method and audience API are ready, what do I do now?

You can log in to partner.bluekai.com, select Apps > Develop Apps, and create a new app. The app development tool enables you to quickly enter all the information needed for the integration. For details, see developing an app.

I am receiving data via SDT. Do I need a new server endpoint or change anything with my current one?

You can use your existing server endpoint for the audience injection integration, but you need to be able to process an additional field that includes your external audience ID. For example, if you are receiving data via SDT real-time, your JSON POSTs will include a field such as "external_audience_id":"123-abc-456". If you receive data via SDT batch, you need to parse the external audience ID from the query string of the pixel URL field such as: https://stags.bluekai.com/site/15415?limit=0&external_audience_id=123-abc-456.

I get error messages when trying to save my app. What is wrong?

Your Oracle Data Cloud partner manager can schedule a meeting with the engineering team or provide you with a contact who you can email. Note that you must have validated your audience APIs with the provided cURL commands to receive support from DMP Engineering.