Ad network integration guide and testing

The first step is to define your AppsFlyer click URL. When a user clicks on an ad, a redirect is put in place from your ad network attribution link to the AppsFlyer attribution link.

Below is the redirect flow from the end-user click to the final destination (Appstore):

The click URL should be in the same format for all future campaigns.

See below AppsFlyer's base attribution link with a detailed explanation per macro:

https://app.appsflyer.com/app_id?pid=mediaName_int&c={campaign}

AppsFlyer Base URL	Description
https://app.appsflyer.com	AppsFlyer End-Point
app_id	Application Unique ID - Dynamic value changed per app (provided automatically by AppsFlyer)  Example Android - com.appsflyer.sample iOS - id1234123412
pid=	Media source name concatenated with _int to identify integrated networks (provided by AppsFlyer)

In addition to the above, ad networks can specify available macros by adding parameters to the URL. For example, Click ID, Publisher ID, Campaign ID, Ad Type, Cost, etc. These macros are then used by AppsFlyer when sending postbacks to the ad network.

By using macros, the ad network specifies what data it wants AppsFlyer to include in the postbacks.

Below is a list of the most important macros:

Name	Description	Parameter name convention	Field type and char limit
Campaign Name	Campaign name	c	String 100
IDFA (iOS only)	The IDFA of the iOS device from which the click/impression is received	idfa	String 40
GAID (Android only)	The Google Advertising ID (GAID) from which the click/impression is received	advertising_id	String 40
Click ID	The ad network unique click identifier	clickid
Publisher ID	Ad network publisher id. If the network works with several different publishers they can be identified by using the site ID	af_siteid	String 24
Sub Publisher ID	Ad network sub_publisher id. If the network’s publishers have additional sub_publishers or site ids, they can be identified by using sub_site ID	af_sub_siteid	String 50
Cost 1. Cost model (i.e. CPI, CPC, CPA) 2. Cost value (the actual cost in numbers – i.e. 1.99) 3. Cost currency (i.e. USD)	The cost of the campaign/ad-set/ad. This is important so the advertiser can see ROI and eCPI	Cost af_cost_model af_cost_value af_cost_currency	String 20 String 20 Enum 3
Ad type	Use one of the following name conventions: search_text banner interstitial video rewarded_video playable sponsored_content audio	af_ad_type	String 24
Incent or non incent campaign	true/false	is_incentivized
Server-side click or AppsFlyer redirect	true/false	is_s2s

For the full list of available macros, see here.

Example:

Base Attribution Link Template:

https://app.appsflyer.com/com.appsflyer.sample?pid=mediaName_int

Android attribution link parameter example:

https://app.appsflyer.com/com.appsflyer.sample?pid=mediaName_int&clickid={clickid}
	  &c={campaign}&advertising_id={advertising_id}
	  

The final attribution link looks like this:

https://app.appsflyer.com/com.appsflyer.sample?pid=mediaName_int&clickid=123456
&c=test_campaign&advertising_id=1a11a11a-2b2b-3c3c-4d4d-111a1a11a111

iOS attribution link parameter example:

https://app.appsflyer.com/id123412312?pid=mediaName_int&clickid={clickid}&c={campaign}&idfa={idfa}
	  

The final attribution link looks like this:

https://app.appsflyer.com/id123412312?pid=mediaName_int&clickid=123456
	  &c=test_campaign&idfa=AAA11AA-B2BB-333C-D4444444444
	  

Impression Attribution

AppsFlyer also allows ad networks to get attributions based on impressions.

To send impression data to AppsFlyer you can use the same structure as in the above attribution link. The same parameters used for click URLs are used for impression attribution, except:

1. URL base - replace http://app. with http://impression.

2. Lookback parameter - replace af_click_lookback with af_viewthrough_lookback.

In order for AppsFlyer to attribute an install from an impression, ad networks must include the device ID in each call.

For more information, see this article.

The second step is to define the global install postback. An install postback URL is a request sent to the ad network notifying them of a successful install conversion. This call can contain all the relevant macros placed on the click URL.

Example:

http://YourDomain.com/postback?clickid={clickid}&af_siteid={affiliate_id}

The base install postback structure can be changed according to specific ad network preferences.

For the full list of available parameters, click here.

AppsFlyer can also provide static parameters per install conversion postback. Such parameters can be advertiser ID and key or password for allowing postbacks.

These parameters are added by the advertiser in the AppsFlyer UI.

In addition to the attributed installs, AppsFlyer can also send a postback for every non-attributed install. These postbacks can be marked with a specific parameter called “can claim”.

&can_claim=1 indicates an install that is attributed to the ad network.

&can_claim=0 indicates an install that is attributed to another network or organic source.

http://yourdomain.com/AppsFlyer?clickid={clickid}&can_claim={1\0}

Non-attributed installs are missing specific parameters such as the Click ID which are available only when reporting attributed installs.

This section is relevant only for ad networks that are able to receive in-app event postbacks – if you are unable to support this, skip this step.

The third step is to define the global in-app events postback endpoint and macros.

An in-app postback is a request to the ad network notifying them of a successful in-app conversion. When AppsFlyer measures an in-app conversion, it determines which ad network is responsible for generating the specific event based on the install conversion. AppsFlyer then attributes the in-app event to that ad network.

Global in-app event postback example:

http://YourDomain.com?clickid={clickid}&event_name={event-name \ mapped-iae}&currency={currency}&value={revenue}

All install parameters are also available in the in-app event postback.
For the full list of available macros, see here.

You can either pre-configure the event tags to standardize the information the advertisers can send you, or you can leave the event tag open for advertisers to enter free text.

Example of free text event tag:

Example of pre-configured event tag:

This section is relevant only for ad networks that are running retargeting campaigns – if not, skip this step.

Re-attribution - having the targeted user engaging with the retargeting campaign and causing them to re-install the app.

Define which postback you want to receive for re-attributed users.

You can choose between:

1. Your install postback, including a unique flag for the re-attribution
2. Your in-app event postback, including a unique flag for re-attribution
3. A custom postback

For more information about retargeting (re-attribution and re-engagement) including the structure of the attribution link and relevant parameters, see here.

This section is relevant only for ad networks that are running retargeting campaigns – if not, skip this step.

Re-engagement - when an existing user that has the app installed engages with the retargeting campaign.

Define which postback you wish to receive for re-engaged users.

You can choose between:

1. Your install postback, including a unique flag for the re-engagement
2. Your in-app event postback, including a unique flag for re-engagement
3. A custom postback

For more information about retargeting (re-attribution and re-engagement), including the structure of the attribution link and relevant parameters, see here.

Copy the attribution link that follows:

https://app.appsflyer.com/com.appsflyer.adNetworkTest?pid=YOUR_PID&c=YOUR_CAMPAIGN
	  &af_click_lookback=7d&af_click_lookback=7d&clickid={clickid}
	  

Change the following parameters:

1. pid (YOUR_PID) - your partner id (supplied by AppsFlyer)
2. c (YOUR_CAMPAIGN) - any campaign name
3. clickid - a random number or id

Send the attribution link to the test device. Open the link in the browser and install the app.

Once the app launches the following screen appears:

If you don't see this message, make sure that the attribution link is formatted correctly. Uninstall the app and reinstall using the attribution link.

Once you install and launch the app, you can see the results in your dashboard.

Open your AppsFlyer dashboard.

Before you can start testing in-app events, you need to map AppsFlyer events to events as they are defined by your ad network.

In your AppsFlyer dashboard, click on Integrated partners and choose your ad network. Under the Integration tab, scroll down to In-app events settings. Choose the in-app event and map it to the corresponding event:

Scroll down and click Save.

In-app events that are sent to AppsFlyer are also attributed to the ad network that generates the app install. You can test in-app event attribution directly from the app.

Once the app launches, click on EVENT TRACKING TEST.

In the next screen, click on any button to trigger an in-app event:

Now you can generate an attribution Link to test install attribution.

Add parameters to the attribution link according to your requirements and the data that you want to record.

Send the attribution link to the test device. Open the link in the browser, install the app, and launch.

Launching the app is crucial for the attribution flow. If the app is not launched, no attribution is recorded.

You can then view the install in your dashboard.

Generate an attribution link. You can use the same instructions as listed above. Send the attribution link to the test device and navigate to it using the device's browser.

The following screen appears:

This is the expected result. Since the app is not live, the attribution link doesn't lead to any app store. However, the attribution link is still valid for attribution purposes. the attribution link and its parameters are recorded by AppsFlyer servers and the data is used for attribution.

Install the app on the test device using the file that the advertiser provides you and then launch the app. Delete the app and repeat the process (to generate several installs). You can then view the installs in your dashboard.

If the advertiser enables the permission Allow to configure in-app events postbacks, you can map AppsFlyer events to the events that you log in your servers.

In your AppsFlyer dashboard, click on Integrated partners and choose your ad network. Under the Integration tab scroll down to In-app event settings. Choose the in-app event and map it to the corresponding event:

Once you know which in-app events the advertiser records, and event mapping is in place, trigger a few events from the installed app.

In the in-app events postback report, you can find data such as the postback URL and mapped parameters. Use the data in the report and compare it with the data in your servers (from the postback) to make sure that data from postbacks is accurate and properly recorded by your servers.

After exporting the in-app events postbacks report, you can look into the report to verify the following:

1. The event is attributed to you as an ad network, under the field Media source
2. The event name is correct, under the Event name field
3. The postback, if enabled, contains the event name and value, under the Postback URL field
4. In-app events are mapped correctly under the Postback URL field

If you wish to work with AppsFlyer clients, you must be an AppsFlyer integrated partner.

In order to register for an AppsFlyer Partner account fill in this form, and a member of the partner development team will be in touch. When filling in the form, specify an email address that has never been used before in AppsFlyer. Alternatively, you can contact them directly through partners@appsflyer.com.

If you need to update your integration with AppsFlyer (for example, updating the postback endpoint), contact integrations@appsflyer.com with your integration update request. Make sure to include your integration's PID.

An advertiser can grant permission to a partner to configure the integration with that partner.

It's easier for you as a partner to test campaign configuration if you have permission to edit and change the integration of the advertiser setup with your ad network.

The permissions are (depending on the advertiser account):

• Integration parameter configurations
• In-app event configuration
• Retention reports
• Protect360 dashboard

For more information, visit our guide on Providing permissions to ad networks.

Installs appear in the dashboard up to two minutes from the moment of install.

Reports for installs and in-app events take up to 15 minutes to be produced.

If you are unable to add an app to the App search screen, make sure that the advertiser adds the app to their dashboard first.

If you run test installs with a client but don't see any installs on your Appsflyer dashboard:

1. Make sure the advertiser allowlisted the devices you are using for testing.
2. If you run campaigns using S2S probabilistic modeling, ensure that your integration is validated by AppsFlyer. Contact your PDM.

If you believe that postbacks are not sent to your servers:

• Make sure that the postback endpoint is active
• Make sure that the postback endpoint is the correct one - contact your PDM if it is not the correct endpoint

In-app event postbacks must be enabled in your configuration with the advertiser:

• Ask the advertiser to enable in-app event postbacks.
• If the advertiser grants you permissions for in-app events configuration, make sure to enable In-app event postbacks in the Integration tab.
• The names of SDK Events must be mapped to the names of events as configured in your own system.

  
  

Ad networks get visibility to their setup done by advertisers, but not when it's done by agencies. Therefore, when an agency, but not the advertiser, maps in-app events for postbacks to a network, the ad network sees this section as inactive, although it is actually active for the agency.

If click data is missing from postbacks, make sure that the AppsFlyer link has all the data that you want to be returned to you in the postbacks. See our attribution link guide for more information.

If the advertiser configured the ad network to receive all postbacks, postbacks for events not attributed to the ad network don't contain click data.

If revenue data is missing or appears as N/A in the advertiser postbacks, there could be two possible reasons:

• The advertiser has decided not to share revenue data.
• The advertiser has defined the in-app event incorrectly.

You need to place the AppsFlyer attribution link as the redirect URL on your servers. Then you need to use your server's own attribution link to run a full test.

Make sure to map the parameters of your network's attribution link to AppsFlyer's attribution link.

If you see data in the dashboard but that data is missing in your servers, verify that advertiser provides the necessary credentials or keys when configuring the integration with your ad network.

The advertiser should add any credentials, key, or tokens in the General Settings section of the Integration tab.

If your network requires credentials or keys for integration and the advertiser doesn't provide them, postbacks from AppsFlyer are rejected by your servers. Data cannot be posted to your server and is therefore missing.

If you test integration with an advertiser and no data (installs, in-app events) is available, follow the suggestions below:

• If the issue happens with any advertiser, contact your PDM
• If the issue happens with only one advertiser or a few advertisers:
  • verify with the advertiser that they implemented the AppsFlyer SDK in their app
  • verify with the advertiser that the SDK implementation is correct

The advertiser asks you to configure the integration but the configuration is locked and all the options are grayed out.

Ask the advertiser to grant your network permission to set up the integration.