Integrating Adjust: A Guide for Networks

Introduction

Adjust is an independent, third-party marketing attribution tool. Our technology tracks and attributes mobile marketing engagements, providing third-party partners with accurate, easy-to-receive attribution data that reduces discrepancies and simplifies the data integration process.

This guide for networks explains how to integrate with Adjust's Campaign Wizard. This is the simplest way to make sure your client's tracker URLs are correct and their callbacks reach the correct endpoints.

Registering as one of our Technology Partners is the easiest way to integrate with the Campaign Wizard. To register, please complete the Adjust Technology Partners registration form with as much information as you can. For example, if you note your install callback URL on the form, your client will be able to build tracker URLs with your install callback URL included directly in their dashboard. If you have questions about how to fill out the form, please reach out to us at integration@adjust.com.

If you have already registered as a Technology Partner, please skip ahead. We'll show you how to set up callbacks.

If you aren't ready to integrate with the Campaign Wizard, we'll show you how to manually set up trackers for campaign tracking before we move on to structuring client callbacks. You'll also learn how to add custom parameters to callbacks, send publisher IDs or campaign data to your client's dashboard, and how to test your setup before receiving live traffic.


Manually set up tracker URLs for campaign launch

Adjust uses tracker URLs to record clicks and impressions for your customer's campaigns and to send callback data directly to your servers. Your client will create tracker URLs in their dashboard and share the relevant ones with you directly.

Every tracker URL contains a unique tracker token; each token is at least six lowercase, alphanumeric characters. This guide uses a minimum-length tracker in all examples. Please always use the whole tracker provided by the advertiser.

Example click URL:

https://app.adjust.com/abc123
Example impression URL:
https://view.adjust.com/impression/abc123

In these examples, abc123 is the tracker token.
 

Step 1: add your network macros to our tracker URLs with campaign structure parameters

First, you'll add campaign structure parameters together with your macros. We'll populate these with the data your clients need for audience segmentation. We offer three levels of parameters below a network level tracker, which gives your clients four levels of data segmentation to use in their reporting.

Here are the names of the available campaign structure parameters:

  • campaign: one level underneath a top-level tracker
  • adgroup: two levels underneath a top-level tracker
  • creative: three levels underneath a top-level tracker
These names might look like they suggest what type of information you should be tracking at each level, but you can customize each of them to fit your client's needs. Many networks, for example, choose to track publisher and creative IDs with these parameters.

You'll use the parameters in descending order of segmentation. In other words, the campaign parameter is for your largest groups (campaigns, countries, or regions). The adgroup parameter is for a smaller level of segmentation within your campaign-level groups (for example, who you're targeting). Finally, the creative parameter is for the smallest level of information, for segments within your adgroup-level groups. Here's an example of what multiple layers of segmentation could look like:
campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}
And here's an example of a tracker URL with those campaign structure parameters added:
https://app.adjust.com/abc123?campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}

In this example, {campaign_id}, {publisher_id}, and {creative_id} are not Adjust placeholders. They are your click macros and are specific to your server. Your server will replace the macros and send us the campaign ID, publisher ID, and creative ID data specific to your client's campaign.

If you have any questions, feel free to reach out at integration@adjust.com.

Note: Campaign structure parameters are case-sensitive and must be lowercase, otherwise we won't recognize them. You can enter data for up to 3 sub-levels of segmentation, but if these conflict with the preexisting setup (for example, if you add a campaign parameter to a second-level tracker ID), we will prioritize the data from the tracker token. Please confirm which sub-levels are still available with your client; they may already use some of these levels. Make sure you agree on the structure of their campaigns.
 

Step 2: append advertising identifiers to improve conversion tracking

Next, we'll ask you to include a unique advertising identifier in your client's tracker URLs. A unique advertising identifier increases accuracy and is the easiest and most secure way for us to attribute users.

Note: Our technology can use digital fingerprinting to track conversions, but these variables can change (and expire), so conversions may be under-reported. If your client would like to use fingerprinting-based attribution, they must enable it in their Adjust dashboard. Fingerprinting is set to OFF by default.

We accept most advertising IDs and hashes. Advertising IDs are passed using Adjust parameters.

Here's an example of a tracker URL with an identifier parameter added, using the tracking link from step 1 with our tracker token and campaign structure parameters already attached:
https://app.adjust.com/abc123?campaign={publisher_id}&adgroup={sub_publisher_id}&creative={creative_id}&gps_adid=(your_identifier_macro)
With iOS apps, you can send us the raw IDFA. Use the IDFA parameter with your macro. Here's an example of what that would look like:
https://app.adjust.com/abc123?campaign={publisher_id}&adgroup={sub_publisher_id}&creative={creative_id}&idfa=[your_idfa_macro]

The entire list of device identifiers (and their formats) we accept is available in the table below:


Advertising IDs

gps_adidRaw Google advertising IDLowercase, with hyphens
gps_adid_upper_md5Hashed Google advertising IDUppercase, with hyphens, SHA1
gps_adid_upper_sha1Hashed Google advertising IDUppercase, with hyphens, SHA1
gps_adid_lower_sha1Hashed Google advertising IDLowercase, with hyphens, SHA1
idfaRaw IDFAUppercase, with hyphens
idfa_lower_md5Hashed IDFALowercase, with hyphens, MD5 hash
idfa_lower_sha1Hashed IDFALowercase, with hyphens, SHA1 hash
idfa_upper_md5Hashed IDFAUppercase, with hyphens, MD5 hash
idfa_upper_sha1Hashed IDFAUppercase, with hyphens, SHA1 hash
idfa_shortRaw IDFAWithout hyphens
fire_adidRaw Amazon Fire advertising IDLowercase, with hyphens
win_adidRaw Windows advertising IDWithout hyphens


Device IDs

ParameterID TypeFormat
android_id*Raw Android IDLowercase, without hyphens
android_id_lower_md5*Hashed Android IDLowercase, MD5
android_id_lower_sha1*Hashed Android IDLowercase, SHA1
android_id_upper_md5*Hashed Android IDUppercase, MD5
android_id_upper_sha1*Hashed Android IDUppercase, SHA1
idfv**Raw IDFVUppercase, with hyphens
mac_upper_short_md5*Hashed Wifi MACUppercase, without colons, MD5
mac_upper_sha1*Hashed Wifi MACUppercase, with colons, SHA1
win_naidRaw Windows network adapter IDLowercase, with hyphens
win_hwidRaw Windows Store hardware IDWithout hyphens

*Adjust only uses the Android ID and MAC address for attribution when the gps_adid is unavailable.
**The IDFV should be used when running cross-promotional campaigns (e.g., via email) targeting users with LAT enabled. The IDFV provides more accurate attribution than only relying on device fingerprinting.


Step 3 (optional): set up server-to-server tracking for clicks or impressions

If you do not support third-party redirects, you can send clicks or impressions to Adjust server-to-server (s2s).

In order to correctly analyze server-to-server clicks, you need to show us that the click is reported from a server, and not the end user. Server-to-server clicks also require an advertising ID. They cannot benefit from fingerprinting logic, so you must provide advertising IDs for tracking (see section 2). There's one exception: if you're running Android campaigns, you have the option to pass a referrer instead.


3.1 S2S clicks and impressions via advertising ID

Just like in step 2, you need to provide a click macro for an advertising ID that your ad servers can replace with a correct ID. Here's an example of a correct server-to-server click call with an IDFA placeholder and click macro as the required advertising ID (the placeholder for IDFA is [idfa]):
https://s2s.adjust.com/abc123?campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}&idfa=[your_idfa_macro]&s2s=1
The incoming click includes any of the advertising IDs you specify in your campaign structure parameters, as well as the Adjust s2s parameter set to 1. Without these parameters, your clicks will be ignored (we do this in order to prevent bot fraud), and we will not report any attributions for your campaigns. You can specify more than one type of advertising ID. Here is an example of what that tracker URL would look like:
https://s2s.adjust.com/abc123?campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}&idfa=[your_idfa_macro]&gps_adid=[your_gaid_macro]&s2s=1

Impressions can also be sent server-to-server. Setting up server-to-server impressions is very similar to the process for clicks. Create a tracker URL according to the steps in the previous section, then make sure to add the parameter s2s=1. If you want to attribute installs to impressions server-to-server, advertising IDs are a must.

If you would like to attribute impressions to fingerprinting, you are required to send the following information:

  • Device type (device_type), (device_name)
  • Operating system (os_name)
  • Operating system version (os_version)
  • Language (language)
  • IP address (ip_address)
  • User agent (user_agent)

3.2 S2S clicks via referrer

If you do not have access to advertising IDs on click and you are running Android campaigns, you can send s2s clicks with a referrer instead.

You must pass the same referrer to the Google Play Store when redirecting users there. The Play Store will broadcast the referrer once the app has been installed and opened, and our SDK will receive the information and send it to our backend, where it will be matched against the referrer (sent via click).

To implement, you'll send a call to Adjust that could look like this:
https://s2s.adjust.com/abc123?campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}&external_click_id=your_network_[clickid]&s2s=1
As well as one to the Google Play Store:
https://play.google.com/store/apps/details?id=my.app.id&referrer=adjust_external_click_id%3Dyour_network_[clickid]%26.....

Important: Both external_click_id and adjust_external_click are mandatory parameters. Both must be set up properly.


3.3 Sending multiplatform app data with S2S clicks

If your client is utilizing s2s clicks as a multiplatform app, they may want to see their click and impression data separated by operating system. If you aren't using s2s clicks, we're able to display the os_name. However, when using s2s clicks, we have a different solution for distinguishing this data.

In this case, you must append the os_name parameter to your tracker URL. To provide your client with device type and IP address information, use the device_type and ip_address parameters, respectively. Here's an example:
https://s2s.adjust.com/abc123?campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}&idfa=[idfa]&s2s=1&device_type=[device_type]&os_name=[os_name]&ip_address=[ip_address]
Similarly, these placeholders should be determined and replaced by your ad server.

Note: We support and can interpret a range of device type names; however, they should conform to a format without version numbers, and os_name should be all lowercase. For example:
iphone, tablet, mobile, ios, android, windows

That's everything you need to know about manually setting up tracker URLs with your clients. If you have questions, please contact us at integration@adjust.com. In the next section, we will show you how to set up callbacks. Adjust callbacks provide real-time data and can be fired to any endpoint, whether that's an ad server or business intelligence (BI) system.


Manually set up callbacks from Adjust

Adjust allows you to dynamically attach callback URLs directly to tracker URLs. This means that the callback is directly attached to the tracker URL and automatically fires a callback to your endpoint upon conversion. We don't make you hardcode callbacks into our server. This is unique in our industry; with this approach you can easily redefine your callbacks as necessary. Remember: your client will provide you directly with the tracker URL for their campaign.

You can receive callbacks for any event your client gives you permission to track, including clicks, installs, and in-app events triggered by your traffic. We strongly encourage you to use our Tracker URL Generator to set up your Adjust callbacks. This tool lets you enter a number of callback URLs along with your placeholders to automatically create error-free URLs. This page also contains a link to a list of our available placeholders. Take a look at the list to get an idea of the wide range of data points available to you.

For example, our install_begin_time and install_finish_time placeholders help prevent click spamming. Our engagement data placeholders can help clients determine everything from a user's first attribution source to the timestamp of their latest reattribution, and we offer a range of Google and Facebook-specific parameters for those who are certified as Google Partners and Facebook Marketing Partners.

If your client would like you to receive revenue or custom app data points that don't appear in our dashboard (transaction ids, for example), then they must set up partner parameters (available on session, install, reattribution, and event callbacks), and enable the Revenue Sharing and Parameter Forwarding toggles in their dashboard under Partner Setup > External Data Forwarding.

You can set up callbacks for any events tracked by your client that you have received permission to track. Our callback generator will help you create callbacks that are correctly encoded. Continue reading to learn more.


Using the Tracker URL Generator to manually set up your Adjust callbacks

As we go through this example, we will use the same tracker URL from the section above on creating tracker URLs. This URL already has the tracker token, campaign structure parameters, and advertising ID parameter added. Here's a reminder of what it looks like:
https://app.adjust.com/abc123?campaign={publisher_id}&adgroup={sub_publisher_id}&creative={creative_id}&idfa=[your_idfa_macro]

Let's say your callback is http://your-URL.com/php?country={country}**
**If placeholder data is not available, it will be dropped from the callback.

Instructions

  1. Go to partners.adjust.com
  2. Enter the tracker URL in box 1 ('Enter your links')
  3. Insert your callback URL in the 'install callback' field
  4. Scroll down to the list of placeholders. Confirm the tool correctly recognized your macros.
  5. At the bottom of the page, we'll generate your click URL
In this example, the correct callback URL we generated looks like this:
https://app.adjust.com/abc123?campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}&idfa=[your_idfa_macro]&install_callback=http%3A%2F%2Fyour-URL.com%2Fcallback.php%3Fcountry%3D%7Bcountry%7D

The process for session, reattribution, rejected install, and click callbacks is exactly the same as above. For example, for a reattribution callback you'll attach the reattribution_callback parameter. This will inform you anytime a user is successfully reattributed to one of your campaigns.


Adding your click ID to your Adjust callback

We make it simple for you to receive your network's click IDs/transaction IDs as part of your callbacks. If your server has its own macros/placeholders available (they're often formatted as {click_id} or {transaction_id} but may vary), you only need to include them within the callback portion of the URL.

Here's an example of what your callback URL with the click ID parameter added might look like:
http://your-URL.com/callback.php?click_id=[your_click_id]
Here's how it looks when added to the Adjust tracker URL:
https://app.adjust.com/abc123?campaign={publisher_id}&adgroup={sub_publisher_id}&creative={creative_id}&idfa=[your_idfa_macro]&install_callback=http%3A%2F%2Fyour-URL.com%2Fcallback.php%3Fclick_id%3D[your_click_id]
Event callbacks have an extra step. If you need a callback for a particular event, your client must share the event token with you first. Adjust generates a unique event token for each event they set up in their dashboard. Please ask your client to share this information with you if you would like to set up event callbacks. Below is an example, in which the event token is xyz456.
https://app.adjust.com/abc123?campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}&idfa=[your_idfa_macro]&install_callback=http%3A%2F%2Fyour-URL.com%2Fcallback.php%3Fcountry%3D%7Bcountry%7D&event_callback_xyz456=http%3A%2F%2Fyour-URL.com%2Fcallback.php%3Fcountry%3D%7Bcountry%7D

Note: You may add several event parameters in a row to the same tracker URL, as long as they're separated correctly.

Fraud callbacks are available if your client has activated the Fraud Prevention suite (which includes Adjust's Anonymous IP Filter, Click Injection Filtering, and Distribution Modeling for individual apps in their dashboard. If your client has activated the feature, we will detect and reject fraudulent engagements before attribution.

If you add rejected_install_callback or rejected_reattribution_callback to a tracker URL and we detect fraud, we will return the correct {rejection_reason} value. The current values are: anonymous traffic, too many engagements, distribution outlier, engagement injection, and invalid signature.
https://s2s.adjust.com/abc123?campaign={campaign_id}&adgroup={publisher_id}&creative={creative_id}&idfa=[idfa]&s2s=1&device_type=[device_type]&os_name=[os_name]&ip_address=[ip_address]&rejection_reason=[distribution_outlier]

Note: It is possible for an attribution to trigger both an accepted install callback and a rejected install callback.

For example, if an install can be matched to two clicks and one of the clicks is deemed fraudulent, we would send a rejected install callback for the fraudulent click and a regular install callback for the valid click.

To complete your client's setup, configure their campaigns to redirect users to this Adjust tracker URL and follow our testing instructions below.

Remember: if you fill out the Technology Partners registration form and include your callback URL, it will be automatically available in the Campaign Wizard for your client to add to their tracker URLs as needed and you will not need to manually add it.


Testing your Adjust callbacks

We recommend you test your callback URL before launching your campaign. This prevents us from having to troubleshoot live traffic.

To test your URLS, use our testing tracker, known as the cbtest tracker. The cbtest tracker sends a simulated callback to your callback URL. Example:
https://app.adjust.com/cbtest?install_callback=http%3A%2F%2Fyour-URL.com%2Fcallback.php%3Fparameter%3D{parameter}

This will trigger the callback immediately without requiring a test install. To test, you can use callback, install_callback, or event_callback parameters. When clicked, the cb test tracker won’t redirect you to the app store. Instead, a successful test will lead you to a page that reads as follows:
callbackTest called: http://your-URL.com/callback.php?parameter={parameter}

Check your server logs to see if you have registered the callback; if you have, then everything is running smoothly. To go live, replace ‘cbtest’ with the tracker URL provided by your client.

If you’d prefer to do some end-to-end testing using both a live tracker and a live app, request a tracker from your client to test a live URL. This will behave similarly to the example above. In order to test, you’ll need to use a fresh device or clear our servers’ attribution from your device ahead of time. Please note that we will permanently attribute your device to your tracker when you install the app for the first time

If something’s not right, reach out to us at integration@adjust.com for assistance.


Advanced Security Instructions (optional)

Protecting your callback structure

To maintain the privacy of your callback structure, we can provide you with a placeholder for the static part of your URL. Email us at integration@adjust.com and let us know which parts of your callback are static. Once we’ve set that up for you, you’ll be able to call the placeholder like any other normal callback URL. Here’s an example callback URL:
http://mynetwork.com/secret_handler?track=1&install=1&click_id={click_id}

Where only the click ID is dynamic, we’ll create a placeholder, mynetwork, to correspond to your static base URL, which will turn your visible install callback to mynetwork(click_id).

The alias must start with either http or https, and the full call would look like this:
https://app.adjust.com/abc123?install_callback=mynetwork{click_id}

Doing so requires the assistance of our backend team; to begin the setup process, drop us a line at integration@adjust.com.


Securing your Adjust callback

If it is possible that someone would be interested in falsely triggering your callbacks, you can protect your HTTP handles by allowing only Adjust’s servers to make those calls. The callbacks all come from one of Adjust’s server IPs.

Depending on the structure of your callback interface, you can block fraudulent calls on the application level or use a proxy. For example, here’s what it would look like to use nginx:
location /callback {
                 // add this condition to only check callbacks having an "adjust" parameter
                 // set to 1 for the origin - if this location only processes Adjust calls,
                 // remove the condition
    if ($arg_adjust = 1) {
    allow 178.162.216.64/26; allow 178.162.216.128/26; deny all;
    } }

Using this configuration, you can simply append an &adjust=1 to your callbacks and we will check them for the correct origin IP, making fraudulent calls impossible. If you need assistance setting up your proxy or application, please contact us at integration@adjust.com.

On this topic