advertiser-api-guides | Segments API Guide
The InMobi Segments API allows advertisers to customise ad experiences based on user segments. Using the Segments API, advertisers can customise ads for a specific audience helping improve ad relevance and thus generate more revenue for the promoted app.
Device ID Guidelines
Segments are defined through device IDs, namely, Apple’s IDFA (ida) or Google’s Advertising ID (gpId). See table below for details
iOS
Parameter Name | Parameter Type | Description |
ida
|
String | Identifier for advertiser without hashing. For iOS 6 and above. For more information, click here. |
Android
Parameter Name | Parameter Type | Description |
gpId
|
String | Google Play Advertising ID, without hashing. Please see here for more information. |
Defining Segments
The goal of defining a segment could be either positive targeting or suppression (i.e., negative targeting).
Example:
- In remarketing, a common use case is to target users who have not opened the app for 30 days or more (“Dormant Users”), or users who are high-purchasing users (“High Value Users”). For these cases, a targeting list is required.
- Advertisers can share a suppression list to exclude those users from a campaign’s targeting. These are primarily used for user acquisition campaigns to negatively target users who have already downloaded the advertiser’s app.
Note: The same user can be tagged to more than one segment
Segmenting for User Acquisition and Remarketing
Once segment is created, it will be available for targeting at account level. A campaign manager can use this segment to include or exclude the property at Adgroup level.
API Components
The Segments API has 3 components:
- Creating a segment
- Adding and deleting users from a segment
- Refreshing a segment
Creating a Segment
To serve ads based on user segments, a segment needs to be created first. The parameters for creating a segment are listed below:
Parameter |
Data Type |
Required (Yes/No) |
Description |
|
String |
Yes |
Property ID as registered with InMobi. Click here for details on registering a property with InMobi. |
|
String |
Yes |
Segment name (unique for a property ID), lower-case unique check applied, max 2000 utf-8 characters |
|
String |
Yes |
To indicate the various campaign types the advertiser would like to share the segment with. The acceptable values for dst currently are:
|
|
String |
Yes |
Name of the Tracking Partner registered on InMobi. If not registered, please get it registered. |
Format for sending requests: GET Method
URL Format |
|
URL Example |
|
JSON Response for Success |
|
JSON Response for Failure |
For User Acquisition and Remarketing: { "status":"error_status", "message":"error_message", "code":"error_code" } |
Adding and deleting users from a segment
Advertisers can add or remove a list of devices from an existing segment using this API. The parameters for adding or deleting devices from a segment are listed below:
Note: Refer to the Installs document before tagging an user to a segment.
Parameter |
Data Type |
Required (Yes/No) |
Description |
|
String |
Yes |
The property ID as registered with InMobi. Click here for details on registering a property with InMobi. |
|
String |
Yes |
List of segment IDs (separated by semicolons) that the user is present in. |
|
String | Yes |
List of segment names (separated by semicolons) that the user is present in. Note: This will be used for Remarketing. |
|
String |
Yes |
Device identifier adhering to the guidelines in the device ID section. This one is mandatory for iOS. |
|
String |
Yes |
Device identifier adhering to the guidelines in the device ID section. It is mandatory for Android. |
|
String |
Yes |
Possible values are
These are actions to be performed for a user on given property and segment IDs. Use this parameter to:
|
|
String |
Yes |
The currently acceptable values for dst are:
Multiple values can be separated using a semicolon. Example: …&dstList={ua; ifc}&... |
Format for sending requests
Adding and deleting a single user: GET Method
URL Format |
|
URL Example |
|
JSON Response for Success |
{ "status":"OK", "message":"success", "code":"200" } |
JSON Response for Failure |
{ "status":"error_status", "message":"error_message", "code":"error_code" } |
Notes:
- Device IDs are sent independently in the query parameters
- Double quotes are not required around any parameter
- Segment IDs need to be semicolon-separated, and within a curly bracket
Adding and deleting multiple users: POST Method
Advertisers can upload bulk segment data to add or delete multiple users from a segment. A maximum of 10 MB of data can be uploaded in .CSV format. The .CSV file must be zipped.
Note: You can submit a list of user ids via file upload. The file should have the predefined headers.
URL Format |
|
URL Example |
|
CSV File Headers |
|
Example |
|
Response Content Headers |
|
JSON Response for Success |
{ "status":"OK", "message":"success_message xxxxxx", "code":"200", "jobUrl":"job url to check status of file upload" }
Note: The |
JSON Response for Failure |
{ "status": "BAD_REQUEST", "message": "Invalid file Content found : Internal errors encountered..java.util.NoSuchElementException: No value present", "code":"1004" } |
Refreshing a segment
Advertisers can refresh a segment to update the list of users added to it. The parameters for refreshing the list of devices in a segment are listed below:
Parameter |
Data Type |
Required (Yes/No) |
Description |
|
String |
Yes |
gpmId of the app (provided by InMobi team) |
|
String |
Yes |
Segment id of the segment to be added/refreshed (received from createSegment API) |
|
String | Yes |
Name of the segment to be added/refreshed (received from createSegment API) Note: This is used for Remarketing. |
|
String |
Yes |
The currently acceptable value is ifc (for Remarketing). |
|
String |
Yes |
The source for this segment data |
Format for sending request: POST Method
URL Format |
http://advertiser-content.inmobiapis.com/tpce/v1/upload/segment/refresh |
URL Example |
https://advertiser-content.inmobiapis.com/tpce/v1/upload/segment/refresh?propertyId=sampleGpmId&segmentName=sampleSegmentName&dstList=ifc |
Response Content Headers |
|
JSON Response for Success |
{ "status":"OK", "message":"success_message xxxxxx", "code":"200", "jobUrl":"job url to check status of file upload" } |
JSON Response for Failure |
{ "status": "BAD_REQUEST", "message": "Invalid file Content found : Internal errors encountered..java.util.NoSuchElementException: No value present", "code":"1004" } |
Notes:
- A maximum of 50 MB of data can be uploaded in .CSV format. The .CSV file must be zipped
- The .CSV file can contain upto two columns (
ida
andgpid
) - Of the two columns, only one can be "non-blank" in each row
- The first row should contain one or more of following headers -
ida
orgpId
. The corresponding rows may contain the deviceIds
File Compression Command: gzip file.csv
This would create a gzipped file called
file.csv.gz