Adjust offers an extensive and robust system to provide real-time callbacks to any of your endpoints. Callbacks allow you to sync Adjust data in real-time to your own servers or business intelligence systems.

Adjust callbacks can provide real-time data on each click, impression, install, reattribution, event, rejected install (for accounts with the fraud prevention suite enabled), updated attribution, uninstall, reinstall, reattribution reinstall, and ad spend update that redirects to or passes through your app. As a client, this data is yours - and you can ask Adjust to send it to any location.

In this guide, we will discuss how to implement your callback solution in a way that suits your needs and technical infrastructure. Some people use Adjust callbacks extensively to tap a wide dataset on their own sources for custom analysis, providing crucial data for their in-app mechanics.

Note: The following page contains examples using a minimum-length tracker token. Always use the entire tracker token as displayed in your Adjust Campaign Wizard.

1Terminology

  • Callback or Postback A predefined ping made by Adjust servers to your servers when certain events are triggered.
  • Callback / Postback URL The URL pointing to your servers where data should be sent.
  • Placeholder An instruction to Adjust servers to enter certain data in a particular place.
  • Parameter A value added to a URL to transmit data.
  • Endpoint A specific location on your servers.
  • Encoding Replacing sensitive characters in a URL with safe counterparts.
  • GET A standard type of network request with a certain syntax.

2Adding callbacks in your Adjust dashboard

You can add callbacks by going through each app’s Settings > Raw Data Export > Real-time Callbacks.

Here you will see a list of all the in-app events you are tracking. Press on the pencil icon to edit each event’s callback.

On the screen that opens, add the URL of your endpoint, along with any parameters filled with any of the available placeholders. Please make sure to always specify the Hypertext Transfer Protocol (either http:// or https://). For example, if on every install you want a callback to http://myserver.com/register/, as well as the IDFA, timestamp and tracker name of each install as parameters, you would add:

http://myserver.com/register/?idfa={idfa}&timestamp={created_at}&source={tracker_name}

The phrases in curly brackets are placeholders. Our servers will replace these placeholders with the relevant information being sent to you. The types of data you can receive using placeholders are listed in the Placeholders section below.

You can, of course, use placeholders to assemble other syntaxes than simple GET parameters, such as:

http://myserver.com/register/{tracker_name}/{idfa}/?data={created_at}

Your custom SDK parameters will always be assembled using GET syntax. POST requests are not currently supported in client callbacks.

You can add multiple callbacks by separating different URLs with a space.

2.1Using updated attribution or updated reattribution callbacks

An updated attribution or updated reattribution callback are callbacks transmitted after an install or reattribution callback and only if a user’s attribution data has changed.

Sometimes, Adjust will receive attribution information from a self-attributing network after we’ve initially determined attribution or reattribution. On these rare occasions, where the user’s attribution data has changed, Adjust will update the user’s attribution information in the Adjust Dashboard. When this happens, Adjust can send a callback with the updated attribution information, for the updated attribution event in the Adjust Dashboard.

If you’d like to receive updated attribution information, we recommend that you include the following Adjust Placeholders in your callback string:

  • {outdated_tracker} - Tracker token of the user’s initial attribution
  • {outdated_tracker_name} - Tracker name of the user’s initial attribution
  • {attribution_updated_at} - Timestamp of the revised attribution
  • {activity_kind} - install_update or reattribution_update

Notes:

  • Updated attribution and reattribution information is available as of March 2017.
  • Updated attribution and reattribution callbacks will only contain attribution information and Adjust placeholder data.

2.2Using global callbacks

In addition to specifying specific callbacks for each event, you can also specify a single global callback. Global callbacks are fired on all events, including clicks, impressions, sessions, installs, reattributions and rejected installs.

The callbacks otherwise work exactly as any other callback, using the same placeholders.

You can add a global callback by going through each app’s Settings > Raw Data Export > Real-Time Callbacks and selecting “Edit Global Callback” at the bottom of the page.

Global callbacks are fired in addition to any other callback that you have specified. If you specify the global callback, and also use the same callback URL for a specific event, that callback URL will be fired twice - once as the global callback, and once as the event-specific callback.

You can tell apart the different types of events using the following placeholders:

  • {activity_kind}, which tells you whether the callback was fired for a click, impression, install (for both installs and rejected installs), session, reattribution, uninstall, reinstall, reattribution reinstall, event, or cost update;
  • {event}, which is replaced with event tokens;
  • {event_name}, which is replaced with the name of the event.

To uniquely identify a particular type of in-app event, you should use {event}. {event_name} should primarily be used to receive a human-readable label. The event tokens are fixed, but the event names can be changed at any time, meaning that the names themselves are unsuitable as identifiers.

3Best Practice: Accessing Adjust attribution data externally

In many cases, you may wish to combine Adjust attribution data with data gathered from other sources, such as in-app analysis, internal user records, or broader BI systems.

Initially, you need to determine or develop appropriate endpoints for callbacks. Your data needs to be sent to your servers, where the values of the parameters are recorded. This can range from a simple server script that simply writes the parameters to a database to more extensive setups that also initialize follow-up calculations.

How you design and organize your callbacks depends on what analysis or mechanisms you are looking to power with this dataset. Decide the extent of the data you want, and consider what can be recorded on your own side and what is available from Adjust. Be sure to keep in mind that certain kinds of data may require using custom parameters from the SDK for completion. Adjust performs a majority of the advanced calculations and provides reports on your aggregated data, both online and using export functionalities.

Think of the incoming data like a pivotal table, with one row representing a particular click, impression, install or event. Each row in this table will likely record the time of receipt or the time of creation, a user or device ID of some form, and the action that they have taken.

Let’s imagine you are looking to connect your internal user IDs with attribution data from Adjust. This would allow you to connect your internal records from other sources, such as online usage or more detailed purchase patterns. Imagine answering these questions in your custom analysis:

  • Are my users acquired from a particular demographic more or less likely to return shipments or deliveries?
  • Are retargeted users likely to have been active on my online app before or after being retargeted on mobile?

It is likely that you will create a simple endpoint that records a user’s single action, and which is then queried in your internal systems. You can add the user ID as a custom parameter in your SDK, and define your callback in the Adjust dashboard to send you the device ID and tracker names. You are now be able to tie your internal records to every mobile purchase, registration, level achievement or other in-app event you are tracking.

Note that any users on devices running iOS 10 or later that have Limit Ad Tracking enabled will be untrackable via IDFA. When building a user database, it is strongly advised that you use the ADID ({adid}) as your main identifier. The ADID can be fetched through the Adjust SDK or set as a parameter in your client callbacks.

4Transmit custom data points with dynamic callback parameters

Dynamic callback parameters (DCPs) allow you to send any number of custom parameters on click, impression, install, reattribution, session, or event. If your network uses more parameters than Adjust supports, or you need to collect extra user-specific data for your system, then you can utilize DCPs.

Please note that DCPs are only available on click, impression, install, reattribution, session, and event callbacks.

Instructions

  1. Decide on a name for your parameter (e.g., campaign_name_3)
  2. Append a dcp_ prefix and make it a placeholder on your click, impression, install, reattribution, session, event, or S3 callback (e.g., {dcp_campaign_name_3})
  3. Append this parameter, without dcp_, to your click tracker URLs (e.g., campaign_name_3={campaign_macro})
  4. Submit your click tracker URLs to your ad network and ask them to integrate them into their servers

Once Adjust receives data within these parameters, the information will be sent in your raw data callbacks.

5Best Practice: Using callbacks to deliver user rewards

Any user acquisition strategy will require an attribution mechanism, whether the user is acquired through performance marketing, affiliates, or viral invites. How could you deliver a reward to a user who successfully invites their friends to register for your service?

This is a straightforward setup: invite your friends via social networks, e-mail or chat, and get a small in-app reward or discount. Adjust is designed to establish links between sources and acquisitions, and with callbacks, you can even pipe your data through Adjust to deliver the coins, VIP status, or whatever promise you make your users.

Here’s an example workflow:

  1. One of your users - Bob - uses your app to invite his nephew - Tom. That friend is recruited via an Adjust tracker URL. You can create a standard tracker in your dashboard with the ID “f0ob4r”, and add your user ID as an Adjust label parameter. (For more about campaign structures and tracker generation, please read our tracker generation guide).
     https://app.adjust.com/f0ob4r?label=[user_id]
     
  2. Your app replaces [user_id] with Bob’s ID, and sends the Adjust link via e-mail / SMS / Snapchat to Tom. When Tom clicks the link, Adjust attributes Tom’s click to Bob’s invite.

  3. Tom installs the app, and Adjust attributes that install to Bob. Your servers receive a callback with Bob’s user ID (through the {label} placeholder).

  4. Tom registers for an account. You receive a callback with Bob’s user ID, as well as Tom’s user ID (through a custom SDK parameter).

  5. Now your servers have all the data they need to give Bob a reward, automatically add Tom to Bob’s friend list, and analyze the success of your invitation programme.

You can also access the label in step 3 using delegate callbacks in your SDK, allowing you to instantaneously receive both pieces of data inside the app, and thus power further logic in your app on that basis.

5.1Referral Tracking Workflow

Below is a diagram which shows the extent of the Adjust referral tracking capabilities. refferal workflow

If you have any further questions on particular implementations, feel free to shoot an e-mail to support@adjust.com.

6Reference: Callback timing, responses and evaluating traffic load

Adjust is a real time callback system. Whenever any event hits our systems, they automatically check for any callbacks registered to that event. This includes your client callbacks, any partners that you have activated, and any traffic partners that have hooked into the open postback API. (For more detail on what data your partners can receive via callback, check out the special partners or the Network Integration Guide.

The callback is reliably fired within a few seconds of receiving data on an event. Each install or event may trigger as many callbacks as necessary - you can enter any number of callbacks in your dashboard, activate as many partners as you wish, and add multiple callbacks on the click URL.

The callback server will record the HTTP response of your endpoint, but will not follow redirects, or retry callbacks if your endpoint returns an error code, such as HTTP 500 or 400. It does however assist our support team in troubleshooting if your endpoint returns meaningful responses.

When evaluating how fast your servers need to be and just how much data will be transmitted, you should work upwards from the number of users in your app. If you are solely tracking one-time events, such as registrations, the number of callbacks will scale directly in relation to your marketing activity - one callback for each converting user. Generally, callbacks for conversion events do not place particularly high loads on client servers.

6.1Whitelisting Adjust callback IPs

As an additional security measure, you are able to restrict the incoming callbacks to the specific span of IP addresses that Adjust uses. This way, you can uniquely identify Adjust’s servers - preventing, for example, that your servers would record falsified data from a non-Adjust source.

All Adjust callbacks are executed from two subnets that can be used to create a whitelist in your receiving servers. These are the subnets:

173.208.60.0/23
178.162.200.128/26
178.162.216.64/26
178.162.216.128/26
178.162.216.192/26
178.162.219.0/24
185.151.204.0/22

This is subnet notation. You can see the full, extracted list of IPs here.

7Reference: Adding URL parameters

URL parameters are values that are given a certain name and transmitted with a special syntax that most servers recognize. The standard GET syntax looks like this:

http://callbacks.myserver.com/path?parameter_one=value_one&parameter_two=value_two

Add your parameters after your URL path, placing the first parameter immediately after the question mark and the value following an equal sign. For instance, “ip_address equals 192.168.1.1”. The subsequent parameters are then delineated with ampersands.

You can add any number of parameters onto a URL as long as your servers know how to handle them.

If you want to add an additional parameter to your URL, then simply add another ampersand after the last value, type in the parameter name, and place the value after an equal sign. Generally, you’ll want dynamic parameters. In these cases you can use a placeholder, which is a string between brackets that instructs our servers to inject the dynamic value:

http://callbacks.myserver.com/path?campaign=12346&tracker_name={tracker_name}&idfa={idfa}

It’s important to consider the special status of question marks and ampersands - a misplaced symbol can cause your callbacks to be interpreted incorrectly. Refer to the Encoding section for more.

If you are having troubles receiving the correct values of your parameters, check the following:

  • The special characters are correctly placed and not encoded;
  • There are no unencoded or unintentional special characters such as misplaced ampersands or spaces;
  • The name of any placeholders is correct as in the section below;
  • The placeholders you are using are available at the time you are requesting the callback (click callbacks, for example, cannot include device IDs);
  • and that the parameters are correctly named.

The order of the parameters does not usually have any impact.

8Reference: Custom SDK parameters

In some cases you may want to extend the dataset that is available from Adjust with additional parameters accessible in your SDK. These are custom parameters. These parameters are sent to our servers from our SDK and then sent on from our servers to your endpoint.

Custom parameters are implemented in the app by attaching a dictionary of parameters onto the trackEvent call in the app. For detailed examples of how to assemble these calls, please refer to the SDK readmes.

For example, imagine that you are sending a user ID as a custom parameter from the SDK attached to a purchase event, in effect saying ‘track one purchase from user 123456’. You have also defined a URL in your dashboard, for example:

http://myserver.com/revenue/?tracker={trackerName}

as your endpoint for revenue events. When a purchase is tracked with an additional custom parameter, the custom parameter is automatically appended to your postback URL.

The parameter should not be specified in the dashboard. The custom parameters will be appended automatically onto whatever string you have entered in the dashboard. The keys of the dictionary will make the parameter name, and the parameter value will be set to the values of that key.

In this case, every time Adjust tracks a purchase event, you will immediately receive a callback:

http://myserver.com/revenue/?tracker=name_of_the_tracker_encoded&userID=123456

The Adjust servers intelligently add the correct delineator and syntax regardless of the name and path of your endpoint.

Custom parameters are most effectively used to track data that you need in relation to tracked events, such as user IDs for purchases and registration events, product IDs for purchases, or current states for specific points in the app.

Note that you can only attach parameters onto post-install events. Since the user cannot take any action prior to the install, there are rarely parameters that need to be transmitted on the install, and the available placeholders probably already cover the parameters you may want.

9Reference: Encoding

Encoding is necessary to maintain the correct structure of your URLs, even with complex parameters. If you add complex strings to parameters, such as URLs in values, revenue symbols or e-mail addresses, these should be encoded for maximum security. Encoding replaces sensitive characters with non-sensitive strings (usually two characters after a percentage sign) that can be correctly interpreted by the servers.

If you are adding static parameters in the callback fields in your dashboard, then make sure they do not contain any characters other than letters and numbers. If they do, make sure that you encode them first. Adjust placeholders that use curly brackets ({ or }) should not be encoded. You must, for example, encode spaces before entering them into callbacks. You can easily find encoding tools online that can help you with URL encoding.

Only the content, as shown below, should be encoded - the URL structure itself must be left unencoded:

URL-unsafe URL

http://callbacks.myserver.com/registration?username=Bob Uncle&email=bob.uncle@mail.com&website=http://www.bobuncle.com

Encoded URL

http://callbacks.myserver.com/registration?username=Bob%20Unclde&email=bob.uncle%40mail.com&website=http%3A%2F%2Fwww.bobuncle.com

Many servers and systems will decode incoming URL parameters as standard practice. Make sure that your server also does so before setting your callbacks fully live.

Custom parameters from the SDK should also be encoded, and decoded once received by the server.

10Reference: Available placeholders

You can always find the latest list of available data on our website.

11Filtering or adjusting callbacks on conditions

Conditional callbacks can be used to change the entire callback URL depending on the values of key placeholders. For example, we can filter callbacks on the environment (whether the event is coming from production or sandbox), on device type, as well as any other available placeholders.

You can do this by adding one of the following prefixes:

  • equal, which will apply only to exact specified values;
  • notequal, which will apply to all values except the specified value;
  • contained, which will apply if one or more of the specified values appear;
  • notcontained, which will apply to all values except those specified.

notequal can only be used with one value. If you wish to exclude multiple values, use notcontained.

Structure should be as follows: prefix,{placeholder},value+here,callback. Once all of the key aspects are in place, set conditions will become effective.

Note that values comprising multiple words must be escaped with a +, so my campaign becomes my+campaign.

Lets look at several examples to see how it works:

equal,{environment},sandbox,http://test.your-server.com?source={tracker_name}

Adding the above as your callback in your dashboard would send sandbox activities to a test server.

You can use any placeholder, any value and callback with this syntax.

You can even chain the values:

equal,{environment}{device_type},sandboxtablet,http://test.your-server.com?source={tracker_name}

notequal, contained and notcontained can be used in the same manner.

notequal,{tracker_name},Organic,http://test.your-server.com?source={tracker_name}

Adding the above as your callback in your dashboard would send all activities where tracker name is not Organic to a test server.

contained,{event},abc123;xyz456,http://production.your-server.com?source={tracker_name}

Adding the above as your callback in your dashboard would send all events with token values abc123 or xyz456 to a production server.

notcontained,{network_name},Organic;Facebook+Installs,http://production.your-server.com?source={tracker_name}

Adding the above as your callback in your dashboard would send all events where the network name is not Facebook Installs or Organic to a production server.

It’s worth mentioning that you can add multiple callbacks, with different prefixes, by separating your URLs with a space. Example:

equal,{environment}{device_type},sandboxtablet,http://test.your-server.com?source={tracker_name} notequal,{environment}{device_type},productiontablet,http://production.your-server.com?source={tracker_name} contained,{event},abc123;xyz456,http://production.your-server.com?source={tracker_name}