Carrier Catalog API

Owned by Ryan Hundemer (Deactivated)
Last updated: Jun 22, 2016
4 min read

Digital Turbine Media has a complete app management solution enabling mobile operators to control, manage and monetize campaign applications that re installed (pre or post) on smartphone devices. Through the DT Media Catalog API, carrier partners can quickly integrate and retrieve a full offer catalog allowing a quick time to market while generating new revenue streams.

 
Digital Turbine Media is committed to our partners' success and to ensure that the end to end integration process goes as smooth and quick as possible. Our Technical Account Management team is available around the clock to answer any questions and provide support as necessary.

 
The Catalog API provides a real time, automated feed of all the campaigns currently being offered by DT Media. Within the catalog feed our partners will find all the necessary campaign specific information including payout and budget details. The catalog API allows carrier partners to call programmatically with results returned in industry standard JSON or XML format. Below is a sample of the fields returned in the catalog API.

  • campaignId– Unique numeric id assigned by DT Media for all campaigns
  • name – Advertiser name for the campaign
  • description – Advertiser's description for the campaign
  • application – The Google Play package name (com.appia.sampleapp)
  • clickUrl – The url to use when a user clicks on an ad for this campaign
  • category – The app store category for the app being advertised
  • bilingType – Either CPI or CPC
  • targetedLocations – Country, City or Demographic Market Areas (DMA's)
  • status – Current status of the campaign:
  • Active – currently running and available
  • Paused – campaign has temporarily paused and is inactive
  • Pending – campaign has temporarily paused and is inactive
  • Expired – campaign has ended and is inactive

Full Carrier Catalog API documentation can be found with our Partner Support Site:

 
https://digitalturbine.atlassian.net/wiki/display/PDS/Catalog+API


Since the catalog is updated in a real time manner, we recommend that partners call the API at 10-15 minute intervals to ensure that all new campaigns are retrieved as soon as possible and that any campaigns that may have ended are updated accordingly. The ability to retrieve and make system updates at regular frequencies is very important to ensure that campaigns that have ended are no longer being served to subscribers.


The Carrier Catalog API is secured and uses standard SSL to authenticate and authorize users. The catalog API also has robust Error Handling capabilities which provides great details and user level messages for any troubleshooting purposes.

 
If the partner is side loading the campaign, they will need to scrape the app from Google Play using the package name provided in the Catalog API. To ensure that the app is up to date, the partner will need to check Google Play regularly for updates to the app.

 
A campaign's click url is to be called at the time the app is either loaded onto the user's phone or the user clicks on the ad unit. The click url will redirect the user to the app on Google Play where they can install and open the app. The click event is passed from Digital Turbine to the advertiser's attribution provider to track an install conversion when the user first opens the app.

 
When the app is installed, an advertiser's tracking SDK built into the app will send a notification to the tracking platform that an install has occurred along with information specific to the end user. The tracking provider will then use the user information collected from the install and attempt to match it to a click with the same information. If the tracking provider is able to match a click to an install, a conversion is recorded and a postback is sent to Digital Turbine. Digital Turbine will at this time match the install to its corresponding click and will then record a conversion on our end.

 
Information passed on the clicks must match information passed back on the install when the app is opened for a conversion to be counted. There are a few ways that install attribution can occur.

 
The most common way for apps to be attributed by the tracking provider is with the user's device id being passed on the click tracking link provided in the Catalog API. Digital Turbine allows for the Google Advertising Id and the raw Android Id to be passed on the click. Passing these values on the click will enable 100% matching accuracy. The device id will be received by the tracking platform on the click redirect to Google Play. When the app is installed the SDK will also capture the user's device id and send it back to the tracking platform who will attempt to match it to the device id sent on the click. When this match occurs a conversion is recorded and Digital Turbine is notified with a postback.

 
Another method is Google Install Referrer. This also allows for 100% accuracy but possibly requires a bit more development by the partner. This method will pass a unique value by the tracking platform on the final redirect to Google Play and stored on install. When the app is opened, the broadcast receiver must be initiated by the partner with the Install Referrer that was sent on the click. As before, the Referrer passed back on the install is matched to the Referrer passed on the click and a conversion is recorded and Digital Turbine is notified with a postback.

 
The third most common method of install attribution but far less accurate is Device Fingerprinting. This uses http headers from the user on the click and to match the same headers received on the install. This often involves a combination of the IP Address and the User Agent Header to identify an end user. Since IP addresses can often change, some conversions will be flagged as an organic install because the http headers from the click do not match the headers from the install. This is why we strongly urge partners to pass the user's device id's to ensure proper install matching.