Audience API

The Audience API allows advertisers to target their ads to a specific list of users, making it easy to enhance campaign targeting. Audiences are defined through device IDs, i.e. Apple’s IDFA or Google’s Advertising ID (GAID).

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 identified by advertiser and can be associated to several different campaigns regardless of package name.  This audience list supports a combination of platforms, both IDFA and GAID can be passed through the API in one list. 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:

Objective Set Up Mandatory Fields
Suppression List Block users from a specific campaign Automatically blacklisted Package name & Platform
Targeting List Create retargeting campaigns or target any given audience set Must be uploaded by AM Advertiser ID

 

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
    ironsource-api-details
  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.
Note: Authentication is based on basic HTTP Authentication with HTTPS.

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

Field Description Data Type
audiences A list of objects that contain information about an audience Array
id ID of the audience list Int
type suppression_static / targeting String
name Name of the audience list String
description Description of the audience list String
bundleId Package name of the source app String
platform Platform of the source app – “android” or “ios” or null String
lastModified Last update date of the audience list Date
hasActiveCampaigns – True when audience has an active campaign running
– False in any other case
Boolean

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

Field Description Data Type Required
type supression_static, targeting String Yes
name Name of the audience String Yes
description Description of the audience String Yes
bundleID Package name of the source app String or null
  • No – if audienceType is only targeting
  • Yes – if audienceType is supression_static
platform Platform of the source app:“android” or “ios” or empty String (android, ios) or null
  • No – if audienceType is only targeting
  • Yes – if audienceType is supression_static

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

Field Description Data Type Required
id ID of the audience Int Yes

Example: https://platform-api.supersonic.com/audience/api/{id}
On success: HTTP Response code 200 is returned
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

 

Note: we currently support up to 4000 devices per request or message body of up to 250kb.

POSTRequest

Field Description Data Type Required
addAudience The specific audience list to which you’d like to add device ids List Yes
deviceIds deviceId strings List Yes
removeAudience The specific audience list from where you’d like to remove device ids List Yes

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