Audience API

The Audience API allows advertisers to include or exclude specific users in their campaign, based on lists of device IDs supplied by the advertisers.

How do I define my audience set?

The ironSource Audience API supports two kinds of Audience lists: Suppression and Targeting.

Suppression Lists

Suppression Lists are associated with the campaign through a package name and platform, e.g. “com.facebook.katana” and “android”.   Each Suppression List supports one respective platform, either IDFA or GAID. This type of audience set operates as a blacklist. Once a Suppression List is uploaded into our database, the audience set will automatically be opted out from every campaign that has a matching package name and platform.

Targeting Lists 

“Targeting Lists” are lists of Device IDs which are defined and identified by the advertier, these lists can be included for different campaigns regardless of package name.  This audience list supports both IDFA and GAID which can be update through the API. Targeting Lists aren’t automatically associated to any given campaign; an Account Manager must assist in either opting in or out of the list of devices per campaign.

See the table below for example cases on when to use the above audience lists:

Authentication ID

For our system to identify your API requests, you will need an authentication ID. Follow the below steps to generate this credential:

Generate your Authorization Header and Add it to Your PHP Code

To generate your Authorization header, you’ll need to obtain your ironSource account’s secret key:

1. Log in to the ironSource dashboard
2. Click on your profile in the top right corner of the dashboard and select ‘My Account’ from within the dropdown
3. Then go to the Reporting API tab and you’ll find your secret key
   
4. Next, encode your “ username:secret key” based on the base64 version and add an Authorization header in your code with your encoded username:secret key.

PHP code example to generate a username:secretkey with base64

 <?php
$crl = curl_init();
$base64encoded = base64_encode("[username]:[secret key]");
$header = array();
$header[] = 'Authorization: Basic '. $base64encoded;
 $URL='https://platform.ironsrc.com/partners/publisher/applications/<API Method>';
 curl_setopt($crl, CURLOPT_URL, $URL);
curl_setopt($crl, CURLOPT_HTTPHEADER, $header);
 $response = curl_exec($crl);
 curl_close($crl);
?>

API Structure

The API consists of 5 requests:

Metadata of Audience:

1. Show – displays the details of all existing audiences
2. Create – build a new audience
3. Delete – delete an existing audience

Device Id Updates:

1. AddAudience – Add device list to existing audience
2. RemoveAudience – Remove device list from an existing audience

API Requests

Show

Displays the details of all existing audiences- GET request

Example
Request:  https://platform-api.supersonic.com/audience/api/show

Response will be code 200 for a non-empty list empty / 204 for an empty list

Example of Non-Empty List:

{
  "count": 1,
  "audiences": [
    {
      "id": 1,
      "type": "targeting",
      "name": "batz",
      "description": "batz",
      "bundleId": "com.adsd.sdf",
      "platform": "android",
      "lastModified": "2017-01-31T20:00:00.000Z",
      "hasActiveCampaigns": true
    }
  ]
}

Create

You can easily create a new audience. This creates an empty audience with metadata only.
POSTRequest

Request Example: https://platform-api.supersonic.com/audience/api/create
Request Body:

{
  "type": "suppression_static",
  "name": "batz",
  "description": "batz",
  "bundleId": "com.adsd.sdf",
  "platform": "android"
}

On success: Response code 200 is returned with created/existing ID. { id : 67567fhgf6786786 }

Delete

You can easily delete an existing audience. DELETERequest

Request Example: https://platform-api.supersonic.com/audience/api/{id}

Request Body: { “id”:”67567fhgf6786786″}

On success: HTTP Response code 200 is returned with type, name, description, bundleId, platform.

Response example:

{
  "type": "suppression_static",
  "name": "batz",
  "description": "batz",
  "bundleId": "com.adsd.sdf",
  "platform": "android"
}

Add or Remove Audience

You can add or remove a device list to existing audience in one call.

There are three main scenarios in which you will want to use this API:

1. Add devices to a defined list
2. Remove devices from a defined list
3. Switch a specific device ID from one list to another

POSTRequest

Example

POSTRequest
Request: https://platform-api.supersonic.com/audience/api

Request Body:

• When adding devices, leave the “removeAudience” field empty.
• When removing devices, leave the “addAudience” field empty.
• There should only be values in both the “addAudience” and “removeAudience” fields if you are switching a device id from one list to the other.

Find below three examples of the different scenarios:

1. Add Device IDs

   {
     "addAudience": ["1","2"],
     "removeAudience": [],
     "deviceIds": [
        "66b728c2-f9a4-4d87-82ef-ce07414nili1",
        "66b728c2-f9a4-4d87-82ef-ce07414nili1"
         ]
   }

   On success: Response code 200

2. Remove Device IDs
   

   {
     "addAudience": [],
     "removeAudience": ["1","2"],
     "deviceIds": [
        "66b728c2-f9a4-4d87-82ef-ce07414nili1",
        "66b728c2-f9a4-4d87-82ef-ce07414nili1"
         ]
   }

   On success: Response code 200

3. Switch Device IDs from One List to the Other

   {
     "addAudience": ["1","2"],
     "removeAudience": ["4","5"],
     "deviceIds": [
        "66b728c2-f9a4-4d87-82ef-ce07414nili1",
        "66b728c2-f9a4-4d87-82ef-ce07414nili1"
         ]
   }

   On success: Response code 200