Adjust provides the most flexible in-app tracking in the business. You can define and track as many in-app events as you desire, and set up exactly those events that correspond to your needs.

With power, however, comes responsibility. As a savvy app developer or marketeer, you need to plan ahead and work out your in-app event tracking as it suits your app, use case and workflow.

This guide is focused on methods and mechanics, and does not include code examples. Your code will be different depending on your platform, framework and implementation. For extensive documentation of our SDKs, please refer to their respective readmes on GitHub.

If you have not yet read the Getting Started guide we recommend doing so, as this guide assumes you are familiar with event setup in the dashboard.

1Terminology

  • In-app event
    Any event triggered by a user in your app.
  • Revenue event
    Any in-app event that is tracked with an associated revenue value.
  • CPA
    Cost-per-action, a generic term for traffic pricing based on the number of in-app events triggered by purchased users.
  • Conversion chain
    The procession of various conversion events a user can trigger in an app, from click to install to purchase.
  • Callback
    HTTP request made from one server to another to transmit data
  • API
    An interface to send data.

2Seeing conversions through event tracking

Your event tracking defines what metrics you capture and how you build up your conversion chains. As users use the app, they will prove their engagement with you at various points: through registration, levels of achievement, unlocking content and making purchases.

These are the conversion points that summarize how well your advertising performs. Users that achieve further conversion points - and sources that drive more conversion per user - are more qualitative than users that register and then forget about it. These users are also more qualitative than ones who engage without converting: users who have numerous, long sessions in your app but ultimately do not fulfill your goals.

If you are aiming for viral growth, your most important conversion points may be user invitations and social engagements. Sending a message or hitting a share button are distinct conversion points, and you should track when these events occur to understand what parts of your userbase tend to boost your virality.

Selling products or paid content might make you focus on the purchase as the ultimate conversion, but there additional important steps both before and after users make a purchase. Often, tracking how many users start adding items to a cart indicates where further engagement or offers can help them convert. After the purchase, leaving reviews can tell you which of your users were most satisfied and may be likely to engage again.

In gaming, you’ll quickly be bogged down if you track every achievement or how many stars they achieve on a certain level. Instead, it’s often recommendable to track specific, key achievements: finishing the first three levels, progressing to where other users tend to get hooked, or earning that first addictive achievement.

While most of these events may be interesting to you - let’s say you market a mobile game with viral growth and in-app purchases for monetization. With Adjust, you are free to track as many events as you like: in-app events are free of cost, and completely flexible.

In your analysis, however, you may want to focus on specific points at specific times. Trying to evaluate too many different factors may lead you to conclude that all sources and all users are good, just good in different ways. This is a nice, but unhelpful conclusion for your optimization.

To optimize, you need one or two numbers that capture your goals, rather than ten numbers that are all beneficial but not crucial. That way, a quick glance can tell you just how much juice you got for your marketing dollar.

3Analyzing features using events

Beyond the marketing use case, you can also use flexible in-app event tracking to concisely track exactly what your users focus on in your app. Are they mostly using your mapping feature, or rarely sending emoticons? Will they often extensively configure their setup, or leave it to the defaults? Are they missing some of your best features?

In producing meaningful metrics on your features, it’s important to think about how you will be able to compare usage of different components. Clicking on a button soon after install certainly could indicate that this was the feature they were looking for - or it could indicate that the button was a very bright colour.

Think about where your users are actually engaging with your feature as opposed to merely toying with it. Your users are trying to achieve something and there is a point at which they have done it. If one feature allows more people to arrive at this satisfaction than another, then that may be an interesting conclusion for your further development.

For example, let’s say your app allows users to upload pictures either from the phone’s own storage or from e.g. Facebook. Rather than tracking how many clicks you have on each option, you should measure the completion and satisfaction rates of each by looking at what events occur after the image upload.

4Common events for CPA purchasing

Shifting your traffic purchasing to cost-per-action allows you to narrow down your targeting and optimization toward specific goals within your app, improving conversion rates and mitigating your business risk. To do so, however, you need solid event tracking that your traffic partners can rely on.

CPA purchasing is usually directed toward some particular major conversion event, such as registrations or purchases. These points are usually well-defined and allow you to measure quickly the user’s engagement with the app.

While going deeper into the conversion chain often is tempting, you may sometimes find that deeper conversions - purchases, viral multipliers and so on - may occur too late or in too low of a proportion to be effective for direct optimization. If the feedback on which you optimize only occurs in very small groups, the statistical certainty that you are moving in the right direction will be too low. If the conversion similarly occurs a week or two after you made your optimization, then your feedback isn’t coming quickly enough.

Many of our clients subsequently use early points in the conversion chain or proxies for other events. For example, add-to-cart events serve as a proxy for purchases. These happen earlier and more frequently than purchases, so placements that generate more add-to-cart events on average are usually also good sources for monetizing users. You want your feedback fairly quickly, and you also want it in sufficient quantities to draw conclusions.

5Tracking purchases and revenues

Revenue tracking is a central facility for apps that monetize on in-app purchases. Adjust provides flexible, easy revenue tracking that maps directly to your business model.

Purchases can be tracked by adding the revenue parameters to your trackEvent methods. We recommend that you create separate event tokens for your purchases - usually just one purchase event is enough, but you can of course also create multiple event tokens for different types of purchases. For the same reason as discussed in the Best Practice sections above, we do not recommend using too many different event types, and instead sticking to a handful that are the most meaningful to you.

Any event can be associated with revenues, but it is usually recommended to create dedicated purchase events that fire specifically when a purchase has been made.

In addition to the raw purchase amount, you should state the currency of the purchase. For more detail, check out the next section, Tracking purchases in different currencies.

Check out the respective SDK readmes for the full syntax:

5.1Deduplicating purchase events

The purchase logic is usually tied into a separate system that processes payments and handles the actual payout from users. On iOS, it’s common to use the Store Kit framework to fulfil these functions. On Android, there is existing functionality tied to the Google Play store or third parties such as PayPal.

It’s common to hook Adjust tracking into callbacks or confirmation events sent by these libraries. It is, however, also important to consider the way these libraries deliver confirmations. For example, the Store Kit framework will often send multiple receipts for the same purchase unified under a transaction ID number. This is to ensure that the purchase is always delivered, but it is not optimal for tracking.

Tying your tracking to these duplicated receipts will generate duplicated tracking, resulting in overreporting. Fortunately, you can pass the Store Kit transaction IDs to the iOS SDK and we will deduplicate locally in the SDK prior to tracking the event. Please check the latest up-to-date readme for more detail.

6Flagging unique events

To simplify your SDK integration and analysis, you can specify that certain events should be tracked only once. Events that are configured as unique will be dropped by the database should the SDK register the event more than once for a particular user.

This setting can be found in your Events screen by hitting “Edit” next to an event in your list, opening the “Advanced settings” and dragging the slider to “ON”.

Unique event types are particularly handy when the SDK locally may not be entirely aware of the entire context of a certain action. Using certain methods, apps might not be aware of the difference between a login and a registration, for example. After all, they both result in a logged in user. In this case, you can just trigger both a “registration” and a “login” event, and flag the former as unique.

N.B.: We recommend that you use this feature sparingly. Dropping events that come from the SDK may result in discrepancies against true values. In the previous example, what happens if a user signs up a second time for a new account? When possible, you should prefer to track non-unique events with certain contextual conditions. Keep in mind that you can always use server-to-server events if your app is missing some info locally.

7Tracking purchases in different currencies

You may be handling purchases in various currencies if you have an international client base. For your tracking and analysis purposes, you need an idea of what the aggregate revenues are across different sources.

Adjust offers currency conversion that allows you to send us different currencies for your revenue events via the SDK. Once we receive the data, we convert incoming revenue into your desired reporting currency.

  1. Your purchases are sent to Adjust with an original purchase amount and an original currency.
  2. Adjust converts this currency into the base currency, which is USD.
  3. For your dashboards, reports, and other reporting, you can select a reporting currency in your dashboard. This setting can be made while setting up the app and is permanent.

Your dashboards and reports will use the reporting currency, but you may also receive the base and original currency values in your callbacks. Network partners have the same option to select desired revenue/currency. The full list can be seen in our placeholder list.

The list of currently supported original currencies (that you may send from the SDK) can be found here. In order to convert your incoming currencies to the selected reporting currency, we are using the openexchangerates.org API for real-time conversion.

7.1Currency conversion setup

When you create your app, you have selected your reporting currency. Once selected, the reporting currency cannot be changed. The SDK is able to accept any incoming currency that will be forwarded to our servers, where we convert the incoming currency into the selected currency of your dashboard.

  • While setting up your app in Adjust, select a reporting currency.
  • Set your SDK to send local currencies for your revenue events.
  • We will convert incoming currencies to your selected reporting currency.

8Server-side event tracking

In some cases, your app may not be fully aware of an event which is completed server side. It could be that your app is only aware of certain states, not of an actual state conversion, and that purchases or registrations are completed server side. For these use cases, Adjust provides a server-to-server API that allows you to ping both events and revenues from your server via POST callback.

To trigger a server-to-server event, your server needs to collect the IDFA of the device in question and the local timestamp of when the event was triggered. You also need to pass along the correct app token and event token.

Your server callbacks should be sent synchronously from your server, as it handles the request from the user. The interface will only work for events from devices that have recently been seen by our SDK. All S2S events must be sent within 28 days, and any activity older than 28 days may be rejected. Additionally, all S2S events must be sorted by day, per event token: if a day 3 event on token X is sent after a day 7 event on token X, we will reject the older event.

There is a single endpoint for events:

https://s2s.adjust.com/event

For your POST request to our endpoint, the mandatory parameters are:

Parameter name Example Content
app_token 4w565xzmb54d Adjust app token from dashboard
event_token f0ob4r Adjust event token from dashboard
s2s 1 has to be set to 1
created_at 2006-01-02T15:04:05Z-0700 Device local time, including timezone
device_id See Below Device Identifier(s)
Timestamp encoding and Unix parameter

Please note the created_at timestamp must be encoded.
The example in the table above would need to be sent as created_at=2006-01-02T15%3A04%3A05Z-0700.

It is important to ensure that any timezone that includes a +, such as Z+0200, has the + encoded.
So, 2017-01-02T15:04:05Z+0200 becomes created_at=2017-01-02T15%3A04%3A05Z%2B0200.

If you are using a Unix timestamp, ensure that you use the created_at_unix parameter, for example, created_at_unix=1484085154.

Device IDs for iOS and Android s2s events

If you are sending s2s events for an Android device, it is mandatory that you send the Google Play Store advertising ID (gps_adid), and it is reccomended that you also send the Android ID (android_id).
For iOS s2s events, passing the IDFA is mandatory for some tracking partners like Google, Twitter, and Facebook. Furthermore, it is recommended that you send the IDFV as well as the IDFA. Please note that if a user’s IDFA is not available due to their “Limit Ad Tracking” settings, then the IDFV will be accepted.
Sending this information helps to ensure that events are attributed to the correct installs thus collating your information coherently and representationally.

Other Device IDs

While the idfa and gps_adid are mandatory on iOS and Android, respectively, you are also able to send through any additional device IDs as listed below for the various platforms that Adjust supports.

Parameter Example Content Format
adid 44ae297a759365ca4f8828a616764579 Adjust ID  
idfa D2CADB5F-410F-4963-AC0C-2A78534BDF1E iOS ID for advertisers With “-“
idfv EF76726C-D952-451C-8E1A-4E86938BDC20 iOS ID for vendors With “-“
mac 15118fdce61d MAC address of device (Android only) Short, without “:”
mac_md5 e3f5536a141811db40efd6400f1d0a4e MD5 of MAC (Android only) Upper case, without “:”
mac_sha1 c1976429369bfe063ed8b3409db7c7e7d87196d9 SHA1 of MAC (Android only) Upper case, with “:”
android_id e1cbfb61613b4f50 Android ID  
gps_adid 660e1d86-6796-463a-be86-897993136018 Google Play advertiser ID With “-“
win_adid 107e8ea14329d4a2194ebbb6dc0c0fd7 Windows advertising Identifier  
win_naid 5978aed4-82e5-28cf-8364-dfc64cb1fb84 Windows Phone device ID With “-“
win_hwid JKJbFwIArpGAGDmcBTAvlAUMKJkHAMoSCADlJQkDHWG Windows Phone device ID  
fire_adid df07c7dc-cea7-4a89-b328-810ff5acb15d Amazon Fire advertising ID With “-“

For revenue events, you also need to send a revenue parameter, and you may also optionally specify the environment (e.g. setting the sandbox environment for testing):

Parameter name Content
revenue Value of revenue events, in full currency units (150 = $ 150)
currency Currency code of revenue event, see note below; ISO 4217, e.g. USD or EUR
environment Environment to post the data to, “sandbox” or “production”.

Note that the revenue units have changed from millis to full currency units, and upgrading a pre-existing setup should be done carefully to make sure the unit is updated correctly. The previous amount parameter was transmitted as milli-currency units (990 = $ 0.99).

The currency parameter should always be specified when tracking revenue events.

If the environment is not specified, the event will be pushed to the production environment.

Successfully tracked events will return a response reading OK.

If you receive an error, it is usually because the device was not known to us, or not known by the device IDs that you transmitted.

8.1Sending custom parameters through S2S

As with in-app events, you can also send additional, custom parameters through the S2S event API. These custom parameters are forwarded through your callbacks, allowing you to close the loop in your internal BI systems and have consistent callback outputs for all of your events.

These parameters can be sent as a JSON object (appropriately escaped) through the callback_params parameter. In the example below, a JSON object is appended containing two custom parameters ({"f0o":"bar", "bar":"baz"}):

http://s2s.adjust.com/event?s2s=1&event_token=f0ob4r&app_token=4w565xzmb54d&idfa=...&callback_params=%7B%22f0o%22%3A%22bar%22%2C%20%22bar%22%3A%22baz%22%7D

Similarly, you can send partner parameters using a partner_params parameter.

The JSON object should only contain strings, and should not be nested. If the parameters are incorrectly formatted, the endpoint will return an error.

Custom parameters, whether from the S2S API or through the SDK, are not reflected in your dashboard.

9Sending additional data with custom parameters

Adjust can help you deliver arbitrary data in relation to particular events to your servers, whether for tracking or for further processing. You can use the Adjust SDK to deliver additional parameters upon each event call, such as user IDs, purchase tickets, product categories and so on. In each SDK readme, you can find further detail on how these parameters can be added to an event call.

These additional parameters are designed to deliver data via callback back to your servers, and will not be displayed in your dashboard or Adjust reports. They will also not be processed by our servers longer than required to deliver the callback to you. The Adjust servers will accept the incoming parameters and package these as parameters onto your callback, using the keys you have set in the incoming array.

For further detail on how you can use your callbacks for delivery of additional data, and some related use cases and best practices, please refer to our guide to Working with Callbacks.

10Archiving Adjust-tracked Events

Once an event is archived, Adjust will no longer display that event’s data in the Statistics tab of your Adjust Dashboard. Additionally, archived events will not be included in your Snapshot or Drill Down exported reporting.

Archiving an event is not a permanent action and does not delete the event from Adjust’s system. (If you are interested in disabling tracking for specific events, click here). All archived events will continue to be tracked on the backend and can still be exported via the Adjust KPI Service tool. If an archived event is reinstated, Adjust will display all historically tracked event data, including any event conversions made during the archival period. An archived event never expires and can be reactivated at any time.

To achieve and maintain the highest Dashboard performance, Adjust will automatically archive events that are more than 3 months old and have no tracked history. This means that if you create an event that is not tracked in the 3 months following its creation, it will automatically be archived. In the instance that one of these archived events is triggered, Adjust will automatically unarchive the event and display it in your Statistics tab.

To archive an event manually, follow the insructions below:

  1. Select App Settings > (Data Management) Events
  2. Locate the event that you wish to archive, and select the Archive icon (trash can)
  3. Select the ARCHIVE BUTTON to archive your event

11Unarchiving Adjust-tracked Events

To reinstate an archived event, proceed as follows:

  1. Select App Settings > (Data Management) Events
  2. Navigate to the bottom of the module and select SHOW ARCHIVED EVENTS
  3. Identify the event that you wish to unarchive, and select the Restore icon (arrow)

Once selected, the event will unarchive automatically and all corresponding metrics will display in the Statistics tab of your Adjust Dashboard.

12Native webview event tracking

With Adjust you can track your native web applications for iOS and Android. Utilising a basic bridge between JavaScript and the native SDK, JavaScript functions can call and initialize the Adjust SDK.

Web view support for iOS is possible with usage of native iOS SDK 4.8.0 and higher. Web view support for Android is possible with usage of native Android SDK 4.7.0 and higher.

13Tracking events with Google Tag Manager

As Adjust offers Google Tag Manager integration, any tag you’ve defined can be completely flexibly represented as an in-app event within the Adjust dashboard.

In order to pass this information to Adjust:

  1. Login to your Google Tag Manager account and navigate to the Container section. Click on “Add a new tag”.

    Full setup

  2. Once you’ve selected Adjust as a product, specify your Application and Event Tokens (both are available in your Adjust dashboard within the app settings). If its a revenue event or you want it sent in the sandbox environment - please select these options. You can also add custom or partner parameters to track with each tag.

  3. Once the tag settings are configured, specify which exact in-app events will trigger it. You can either select it for all of them or define specific rules and/or exceptions.

  4. Click on “Create Tag”. You’re all set!