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?

How do I define my audience set?

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

Suppression lists

Suppression lists

Suppression lists are associated with the campaign through a package name and platform, for example "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. After 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

Targeting lists consist 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 following table for example cases on when to use the above audience lists:

Authentication ID

Authentication ID

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

Generate your Authorization Header and Add it to Your PHP Code

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 using secretkey with base64

PHP code example to generate a username using 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

API structure

The API consists of 5 requests:

Metadata of audiences:

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

API requests

Show

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 a 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

Create

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

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

Request body

Request body

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

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

Delete

Delete

You can easily delete an existing audience.

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

Response example

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

Add or remove audience

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

Example

Example

Request example: 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.

The following are 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