InCost API for ad networks

For:
Ad networks
Last update:

At a glance: InCost API, part of AppsFlyer ROI360, lets ad networks programmatically send advertising cost data to AppsFlyer. Doing so provides advertisers with aggregate cost data and lets them understand the true impact of your network.

About InCost API

InCost API is the optimal solution for ad networks to send cost data to AppsFlyer. Ad network partners send detailed advertising cost data to AppsFlyer using the API. AppsFlyer ingests and processes the data, and makes it available to advertisers and partners via dashboards and reports.

Benefits

  • Help your customers understand the true impact of your network with frictionless cost reporting. Without cost data, your customers are missing a crucial piece of the measurement puzzle and can't accurately measure ROAS. As such, they may mistakenly invest in other media sources, negatively impacting your bottom line.
  • Prove your ROI with a solution that guarantees accurate, complete, and real-time cost measurement.
  • InCost API is quick and simple to deploy, and the impact is almost immediate. You also get complete control over how and when you send the data, including the ability to send cost data for up to 90 days back.
  • InCost API supports all campaign pricing models; not just CPI (which is the only model available when sending cost by click).
  • Stand out in the AppsFlyer Partner Marketplace with a “Cost” badge that indicates this is a feature you support.

Implementing InCost API

Prerequisites: For InCost API eligibility, your ad network requires:

  • That 90% of campaigns contain the Campaign ID in attribution.
  • The ability to send data at least 6 times per day for increased data freshness. The specific times are up to the ad network.
  • [If the ad network updates data retroactively] The ability to send data for the last 7 days every time, for increased data completion.

To implement InCost API and start sending cost data to AppsFlyer:

  • Follow the steps in the following table.
Step # Action 
1 Apply for InCost:
  1. In AppsFlyer, from the top menu, select Help > Contact our team.
    The Partner assistant widget opens.
  2. Select Enabling cost measurement and submit your information.
    Once submitted, a ticket opens and an AppsFlyer partner solution engineer will contact you.
2 Make sure campaign hierarchies (campaign ID, and optionally, adset ID and ad ID) are included on your attribution links for more than 90% of your traffic.
3 Get the AppsFlyer API token from the AppsFlyer dashboard.
4 Give the API token to your developer to use in the API authorization header and ask them to follow their instructions to implement the 3 API methods:
  1. Get app list.
  2. InCost upload: Tell the developer what fields to populate the JSON with:
    • Mandatory fields must be populated. Meaning, don't send empty fields. 
    • Media source is restricted to media sources associated with (registered under) your ad network account. Get the list from your partner development manager.
    • Take into consideration the app timezone (as reported via the Get app permission list API) to align cost data dates with that of the app.
    • If there are fields that are not part of your campaign cost reporting hierarchy, don’t include them. For example, adset ID, asset name, ad ID, ad name.
  3. Get job status.
5 Test the integration:
  1. In the ticket thread (from step 1), notify AppsFlyer that the API implementation is complete and get permissions for the following apps which can be used to test the API without using real data:
    • com.cost.app
    • id888123456
  2. In AppsFlyer, from the side menu, select Collaborate > Partner Marketplace, and select the partner.
  3. Click Set up integration.
  4. Select 1 of the test apps.
  5. Open the integrated partner Cost tab.
  6. Turn on the Get Cost Data toggle.
  7. Click Save Cost.
  8. Click Test Connection.
    The API is active.
6 In the ticket thread (from step 1), confirm with AppsFlyer that your integration is operational.
7 Make sure your advertisers enable get cost data in the cost tab of their AppsFlyer integrated partner page. Then they'll begin to receive cost data.

Fields for InCost Upload JSON

Field Mandatory Remarks
date Yes
  • Spend date
  • Format: YYYY-MM-DD
  • Example:2019-12-30
app_id Yes
  • The app ID as it appears in the AppsFlyer platform
  • Format: String up to 250 characters
  • Example: Android:com.app.name, iOS: id123456789
media_source Yes
  • Network name (ID) displaying the ad associated with your ad network partner account in AppsFlyer
  • Format: String 50 characters
  • Example: network_int
af_prt No*
  • Required for agency attribution and cost data.
  • Agency name as it displays on the attribution link and is associated with the agency account in AppsFlyer.
  • Format: String 50 characters
  • Example: agencya
campaign_id Yes
  • Must be identical to the af_c_id param sent on the attribution link
  • Empty string not permitted
  • Format: String 24 characters
  • Example: 123abc
campaign_name Yes
  • Format: String 100 characters
  • Example: my_campaign123
adset_id No*
  • Required if you send adset_name
  • Must be identical to the af_adset_id param sent on the attribution link
  • If your cost reporting does not support adset_id, never send it
  • Format: String 24 characters
  • Example: 123A
adset_name No
  • If you send this field, you must also send adset_id
  • Format: String 100 characters
  • Example:my_adset_name
ad_id No*
  • Required if you send ad_name.
  • This field must be identical to the af_ad_id param sent on the attribution link
  • If your cost reporting does not support adset_id, never send it
  • Format: String 24 characters
  • Example:123AB
site_id No
  • Unique ID that identifies the publisher that displays the ad.
  • Format: String 24 characters.
ad_name No
  • If you send this field, you must also send ad_id
  • Format: String 100 characters
  • Example:Ad-name
geo No
  • The country you recorded as associated with the cost
  • Where possible, this should represent the country where the ad was displayed
  • Format: ISO 3166 2-character country code
  • Example:US, CN, ZA
currency Yes
  • Spend currency type
  • Format: ISO 4217 3-character currency code
  • Example: USD, EUR, ZAR
spend Yes
  • Spend amount using the specified currency 
  • Five digits allowed after the decimal point
  • The value 0 (zero) is permitted
  • Negative values are NOT permitted
  • Don't send , delimiters
  • Don't send values in quotation marks. 
  • Format: Decimal number
  • Example values: 1 1.2 1234.20
channel No
  • Must be identical to the af_channel param sent on the attribution link
  • Format: String 20 chars
  • Example:my_channel
keywords No
  • Format: String 100 chars
  • Example:abc app
* See the remarks column, as in some cases you must send this field.