Getting started

Getting started
This guide takes you through a step-by-step process, from
implementing the SDK to setting up callbacks. We’ve also defined
key terms and KPI definitions to make things easier.
adjust.io is an app download tracking tool that helps you understand which
marketing sources give you your most valuable users.
www.adjust.io | www.adeven.com
1
Contents
Prepare your app . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Setup your app in the dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Integrate the adjust.io SDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Tracking revenue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Tracking events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Enable logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Submit your app into the store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Tracking installs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Setting up a tracker URL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Put your tracker URL in the advertising source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Attributing facebook mobile app install ads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Understanding your data and setting up reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Setting up reports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Advanced topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Sending conversion data to ad networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Changing the target of tracker URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
In-app event and install callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Understanding callbacks and placeholders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
adjust.io placeholders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Using multiple parameters in callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Transmitting custom parameters from in-app events . . . . . . . . . . . . . . . . . . . . . . . 19
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
General terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
KPI definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2
1 Prepare your app
To work with adjust.io, you need to integrate our tracking SDK into your app. Unlike
many other tools, adjust.io uses an open-source SDK that transparently integrates into
your code.
We recommend that you first work out which in-app events you want to measure, if
any, before integrating the SDK and submitting it to the store. Everything else, like
tracker URLs and callbacks, can be added and edited from the dashboard at any time.
.1
Setup your app in the dashboard
First of all, you need to add your app to the adjust.io dashboard.
1
Go to your dashboard on http://adjust.io.
2
On the "Apps" screen, hit
3
Enter your app ID and specify the name.
4
Click "Create app" to confirm.
.
You can change the app settings at any time.
Once you have registered the app in adjust.io, you will receive an app token that will
identify your app. This is key to getting started with the SDK.
Should you have trouble finding your app ID, feel free to get in touch at
[email protected].
3
.2
Integrate the adjust.io SDK
In short, the integration process is pretty much this:
1
Go to the GitHub repo for the adjust SDK and pick your platform.
2
Download and import the source files into your project - follow the readme.
3
Specify your app token as in the readme.
4
Hit the "build" button, lean back, and grab a cup of coffee.
That's pretty much it - but be sure to go through the readme to specify permissions
and set up frameworks correctly. If you have trouble, just email [email protected] or,
if applicable, your account manager.
With the adjust.io SDK integrated just like so, you've just unlocked conversion tracking,
session analysis and standard usage KPIs - in about five minutes.
The next sections will cover how to get more intelligence by sending revenue figures
and using SDK hooks to analyze in-app events.
4
.3
Tracking revenue
If you have a single source of revenue - and that's cool, we don't judge - or if you just
want to track the revenue generated by your app, you can simply just send us revenue
figures when it applies. A single hook lets the SDK know that revenue was generated.
In our open source SDK, it looks like:
iOS:
Android:
[AdjustIo trackRevenue:1.0];
AdjustIo.trackRevenue(1.0f);
The '1.0' here represents 1 cent of revenue - so if you want to register a purchase
worth €9, or $9, £9, or ¥9 for that matter, punch in '900.0'. adjust.io is currency
agnostic, so as long as you're consistent, it doesn't matter which currency you
use.
That's the simplest way - now if you want more detail, you'll want to set up
events.
5
.4
Tracking events
An event is any activity that the user initiates in your app. It is a specific action that
occurs at a specific time, like, let's say, a purchase or a registration.
To track any event in your app, you will first need to set up the event in the adjust.io
dashboard.
1
Go to the "Events" screen and click on the app you're setting events up for.
2
Click new event (you guessed it). Give it a name.
3
When you confirm, you'll receive an event token.
The event token is a unique identifier specifying your particular app and event. This is
what you'll insert in your event hooks and send to our servers. It's a base-36 number,
by the way, how cool is that?
To trigger an event, use the following hooks - here with example event token 'abc123':
iOS:
Android:
[AdjustIo trackEvent:@"abc123"];
AdjustIo.trackEvent("abc123");
One more thing - in-app events are completely free with adjust.io. For the best resolution in
your business intelligence, track as many events as you can. It won't cost you a cent.
Ramp it up: if you want to track an event that generates associated revenue, simply use:
iOS:
Android:
[AdjustIo trackRevenue:1.0 forEvent:@"abc123"];
AdjustIo.trackRevenue(1.0f, "abc123");
In the advanced section of this guide, we're going even further - you can send any kind
of parameter across from in-app events. Current highscore? Product ID? Average flight
velocity of a swallow? You name it.
6
.5
Enable logging
Before we take this any further, let's just make sure that everything's mingling nice
and tidy.
Make sure your SDK is correctly integrated by enabling logging.
The SDKs writes log entries with different frequency depending on the setting. You can
either activate all log entries, or disable logging entirely. By default, the log level is
set to Info - and to change, it, you just have to make a function call to ask the SDK to
change the log level. Here are the different log levels and their function calls:
Level:
iOS:
Android:
Verbose
[AdjustIo setLogLevel:AELogLevelVerbose]
AdjustIo.setLogLevel(Log.VERBOSE)
Debug
[AdjustIo setLogLevel:AELogLevelDebug]
AdjustIo.setLogLevel(Log.DEBUG)
Info
[AdjustIo setLogLevel:AELogLevelInfo]
AdjustIo.setLogLevel(Log.INFO)
Warn
[AdjustIo setLogLevel:AELogLevelWarn]
AdjustIo.setLogLevel(Log.WARN)
Error
[AdjustIo setLogLevel:AELogLevelError]
AdjustIo.setLogLevel(Log.ERROR)
Assert
[AdjustIo setLogLevel:AELogLevelAssert]
AdjustIo.setLogLevel(Log.ASSERT)
Explanation:
Verbose
Everything imaginable.
Debug
Crucial debug logs.
Info
Logs include central points.
Warn
When something is about to go wrong.
Error
When something has gone wrong.
Assert
Logging disabled.
Verbosity is set by default to Info.
7
.6
Submit your app into the store
Unlike other SDKs you may have worked with in the past, the adjust.io SDK is open
source. You can specify the build settings in whichever way best suits your app and
the SDK will follow. Further, since you can inspect the code, you know exactly what it's
up to.
As soon as you start testing your app with the newly installed adjust.io SDK, you will
notice that it is displayed in the adjust.io dashboard as organic traffic.
Organic traffic is traffic that does not come through a tracked adverting source. We
still crunch the same KPIs as any other source. Oh, and just like event tracking, organic
traffic is totally free.
You will see a large spike in installs. This is typical of the first time the adjust.io SDK
is integrated, as each user will register an install when they update to the first version
with adjust.io in it. (An alternative, sweeter explanation is that adjust.io is an install
magnet. This is not true.)
Now let's start tracking install sources.
8
2 Tracking installs
adjust.io conversion tracking mostly matches installs to clicks on a URL. These clicks
come from advertisements, websites or even other apps.
adjust.io links send users to the store, where they go into a black box, and then
installs come out the other side. Using a clever augmented digital fingerprinting
method, we can look at clicks and installs, identify common environmental factors
and to a high degree of confidence attribute the install to a source.
.1
Setting up a tracker URL
To set up a new source, just generate a new tracker URL and start linking to it.
adjust.io will take care of the rest.
1
Log into your dashboard at adjust.io.
2
Go to the "Apps" screen and pick the app you're thinking of.
3
Give it a name and press enter.
The new name will be added to the list and another base-36 number will be
generated - something like http://app.adjust.io/f0ob4r.
If you now click the link on a fresh device and install the app, one click and one install
is attributed to that source.
In the advanced section of this guide we cover redirects of users to places other than
the store.
9
We also provide "grouped trackers" that enable you to aggregate different sources
under a common name, to keep things nice and tidy. Let's say you split up several
different creatives with the same network, or group different targetings under a
common partner name.
If you want to create a group of trackers, use the following notation with double colon:
<Group name>:: Tracker_name
For example
Network::Creative
Partner::Targeting
The system will automatically display the trackers as a group, but the numbercrunching hasn't changed. Let's say halfway through you change your mind and want
things ordered by creatives, not networks - just rename the trackers to have the
creative name before the double colon and the network name after. Hey presto!
If you have any further questions about setting trackers, get in touch with
[email protected] or your account manager.
.2
Put your tracker URL in the
advertising source
Once you have set up all of your install sources, you will need to make sure that the
correct tracker URL is set into your advertisement. Either set this up yourself or ask
your network account manager to do this for you.
The basic set up process is now complete. As soon as someone clicks and installs
your app, it will immediately show up in your dashboard statistics.
10
.3
Attributing facebook
mobile app install ads
adjust.io has been approved by Facebook to measure installs coming from
Facebook's mobile app install ads.
This means that if you are already using the adjust.io SDK, you no longer need
the Facebook SDK to receive all of our KPIs and measurements as well as analyze
Facebook mobile app installs.
You can set up a Facebook app campaign by just specifying the Facebook app ID in
your dashboard.
1
Log into your dashboard at adjust.io.
2
On the "Apps" screen, pick the app you're setting up.
3
Click "Settings", then go to the "Facebook" tab.
4
Enter your Facebook App ID (as found here) and confirm.
That is all you need to do - we'll start checking with Facebook if any installs can
be attributed to them from then on. Go ahead and put your Facebook ads live in
your Facebook ad dashboard. Note that the Facebook dashboard attributes installs
to impressions, whereas we attribute to clicks. This will result in slight differences
between adjust.io and the Facebook dashboard.
We'll create a special tracker group that we'll automatically populate with the
different ad groups you are running.
Please note that the current implementation does not support the transmission of
clicks and we are therefore unable to provide you with their number or conversion
rate. If this should change in the future we'll get in touch.
11
Understanding your data
3 and setting up reports
The adjust.io dashboard displays drill-down data as well as a wide range of different
KPIs that help you understand the performance of your app and the quality of your
users by installation source.
You can also drill down into the data to be able to easily compare different
advertising sources so that you can effectively optimize your advertising campaign.
Each tracker will report a separate set of data and KPIs. Depending on your goals,
different KPIs and metrics may be a better indicator of the performance of your
sources.
See the glossary section for KPI definitions.
.1
Setting up reports
In addition to the online dashboard, you can also set
up customized reporting for individual apps to be
automatically sent to you via e-mail.
1
Log into your dashboard at adjust.io.
2
On the "Apps" screen, click the app you're
looking for.
3
In the "Settings" tab, you can set up reporting
frequency and where we send it.
12
4 Advanced topics
.1
Sending conversion data to
ad networks
adjust.io sends conversion pingbacks to adservers of advertisement networks through
a highly flexible and dynamic callback interface.
Many networks either automatically detect adjust.io trackers and add their callbacks
to the click URL, or have instructed account managers to handle it for their accounts.
When neither of this is possible and you need to provide a network with conversion
data, please get in touch with [email protected] and we'll identify the best way of
solving the situation.
13
.2
Changing the target of tracker URLs
If you want the user to be redirected elsewhere than the app store, you can simply
attach an additional parameter to your tracker URL. For example when using:
http://app.adjust.io/foobar?redirect=encodedurl
You'll have to encode your URL, otherwise there's a risk of shenanigans. To send the
user to another landing page e.g. http://mypage.com instead of the app store, then
encoding your URL would look like:
http%3A%2F%2Fmypage.com
Append this to your tracker URL as above and you'll wind up with this:
http://app.adjust.io/foobar?redirect=http%3A%2F%2Fmypage.com
Any user that passes through an adjust.io URL can be matched to an install.
Be aware that if you redirect your users to an invalid URL or target that does not allow
users to get to the store, then you will not receive any downloads.
14
.3
In-app event and install callbacks
Understanding callbacks and placeholders
If you wish to also keep data from your campaigns in other systems, like BI software or
web service servers, you can receive data on any event or install triggered in your apps
through an HTTP GET request.
These HTTP calls are made in real-time by our servers. The callback setup is made
through the "Events" screen in the dashboard - and no SDK modifications are required
to change them at any time.
1
Log into your dashboard on http://adjust.io
2
Go to the "Events" screen and pick your app
3
In the list of events, that you defined in section 1.3 of this guide, you can
click "Add Callback" for any event, including install
4
To add a callback, provide the URL that our servers should ping when the
event is triggered
Note that installs are also recorded as an event in this screen - so you can set up
callbacks on installs just as well.
If you have any questions or any issues setting this up, feel free to get in touch with
[email protected], or if applicable, your account manager.
15
adjust.io placeholders
{adid}
A unique device identifier provided by adeven
{tracker}
The id of the source the install was attributed to
{event}
The id of the event being called
{idfa}
The id for advertisers from iOS 6 (only available at install time)
{android_id}
The google android id (only available at install time)
Receiving a simple URL ping is one thing, but we can also include a number of
variables available on the device that triggered the event. For example, you could
prepare the callback http://crm.awesome-ltd.com/app and want to include the
placeholder "{idfa}". You would want to define a name and define it as the placeholder,
which would then be filled with an IDFA value:
http://crm.awesome-ltd.com/app?device_id={idfa}
If you set this to a callback on an event, our servers will request this URL when the
event is triggered. When your servers accept this request, you'll receive a variable
named "device_id" set to the IDFA of the device.
In the table below, you'll find all of the placeholders and their availability. Some of
these are only available at install time, others are only available when an in-app event
has been triggered, and so on.
16
placeholder
content
example
click install event
{tracker}
6 digit tracker ID
from adjust.io
o1da2f
●
●
●
{tracker_name}
Name of the tracker,
as set by client
facebook_ad
●
●
●
{app_id}
AppId from store
iTunes / Google Play
332193586
de.is24.android
●
●
●
{ip_address}
IP address of device
8.8.8.8
●
●
●
{idfa}
ID for advertisers
(iOS only)
8C6CBC0D-5F43-4765-A6E6-84DFF3D24707
○
●
●
{android_id}
Android ID of device
(android only)
3accef2d7286d0de
○
●
●
{mac_sha1}
SHA1 of mac
(uppercase with colons)
282f2e4d6324ed731ee1ca4179deb6603f2bc5bc
○
●
○
{store}
Target store of click
ios
android
wstore
wphone
●
○
○
{event}
Event token
from adjust.io
asd123
○
○
●
{adid}
adjust.io device ID
(all platforms)
18546f6171f67e29d1cb983322ad1329
○
●
●
{idfa_md5}
Base-64 encoded
MD5 hash of IDFA
Cz_u68NTpaNfIrXesAtKGg
○
●
●
{country}
Country the device is
located in
US
●
●
●
If a placeholder is not available, e.g. IDFA on Android, it will be replaced with an empty
string. If you are interested in any other placeholder please contact [email protected].
17
Using multiple parameters in callbacks
Let's say you have the following URL as your callback receiver:
http://crm.mycompany.com/api.php
You need this URL pinged for each 'sign-up' action in the app, and you want the source
and device ID of the app to be sent along with the ping. So your callback URL could
look like this:
http://crm.mycompany.com/api.php?action=signup&type=mobile&device={adid}
&source={tracker}
This is the URL that you set in the Events screen as described in the introduction to
this section.
When your servers receive the request, the placeholders will be filled in and find the
variables set to the values you either define statically or expect from the placeholders.
18
.4
Transmitting custom parameters
from in-app events
If you want to receive additional data from in-app events we provide you with an API
to transmit any kind of custom parameters to web-service of your choice.
For example, if you want booking numbers sent to your server when a certain event
happens, you could pass this across as a parameter on the event call.
Please note that we do not store or process custom parameters in any way, due to
the strict privacy standards we adhere to. This means if you have an event sending
custom parameters but no callback setup we will ignore the additional data upon
receiving the event until you provide a callback URL for that specific event.
First you need to setup your application to transmit custom parameters when an
event is triggered. This would look something like:
iOS:
NSMutableDictionary *parameters = [NSMutableDictionary dictionary];
[parameters setObject:@"value" forKey:@"key"];
[parameters setObject:@"bar"
forKey:@"foo"];
[AdjustIo trackEvent:@"abc123" withParameters:parameters];
Android:
Map<String, String> parameters = new HashMap<String, String>();
parameters.put("key", "value");
parameters.put("foo", "bar");
AdjustIo.trackEvent("abc123", parameters);
19
Of course you can combine this with revenue tracking:
iOS:
NSMutableDictionary *parameters = [NSMutableDictionary dictionary];
[parameters setObject:@"value" forKey:@"key"];
[parameters setObject:@"bar"
forKey:@"foo"];
[AdjustIo trackRevenue:1.0 forEvent:@"abc123" withParameters:parameters];
Android:
Map<String, String> parameters = new HashMap<String, String>();
parameters.put("key", "value");
parameters.put("foo", "bar");
trackRevenue(1.0f, "abc123", parameters);
So if you provide the URL:
http://crm.mycompany.com/api.php?a=signup&source={tracker}
We would call:
http://crm.mycompany.com/api.php?a=signup&source=1q2w3e&key=value&foo=bar
If you have any questions or trouble setting this up please contact us
[email protected].
20
5 Glossary
The in-app advertising and analytics industry does not currently have agreed upon KPI
definitions. Alphabetically listed below is our glossary of commonly used terms and
our definitions.
.1
General terms
App Download Tracking
This is when app installs and usage behaviour are attributed to particular user
sources, and the performance of the users sources compared over time. The term
conversion tracking also is commonly used.
Attribution
adeven attributions are clicks plus non-organic installs - that is, any clicks on a tracker
URL as well as any installs that came from a tracked user source. Yeah, 'attributions' is
a general term and we do also 'attribute' in-app events and organic installs.
Click
When we speak of clicks, we exclusively refer to clicks on a tracker link.
Digital Fingerprinting
Digital fingerprinting identifies the mobile device after an advertisement has been
clicked on. This means a set of non-personal data is gathered. If the user installs
and opens the app with the adjust.io SDK integrated, the same process happens.
Our server then matches the device to the advertising source. adjust.io uses ePrivacy
compliant technology.
Installs
We define an install as when a user installs and then opens the app for the first time
Revenue
This is any kind of income that a user generates through in-app purchases or
otherwise through the app.
21
Software Development Kit (SDK)
An app SDK is like a mini program that is put into an app. adjust.io uses an open
source SDK for tracking and analytics. This means that what is in the SDK can be
easily viewed by developers and checked – and can be set up as they like. This
prevents issues that are often associated with closed source SDKs, like unexpected
crashing.
Sessions
A session is every time that a user opens the application. There must be a 30 minute
break between use, otherwise it is counted as the same session. For example, if a
user opens an app every five minutes over a hour long period, this is counted as one
session as there was not a sufficient break between any of the uses.
Tracker
A tracker is an URL, which is attached to a user source. Typically this source is an
advertisement, but it can be anything from an e-mail newsletter, another app, or even
a QR code.
Uniform Resource Location (URL)
A link - the URL is the address of where a resource is located on the web.
.2
KPI definitions
In order to provide you with more meaningful KPIs we do not simply give point in
time data, but rather cohort analyzed groupings by set post install timeframes. Our
dashboard displays the averages for user KPIs either 7 or 30 days after installation or
for the whole lifetime of a user.
Average Revenue Per Paying User (ARPPU)
The average revenue generated by a paying user. Non-paying users are not taken into
account.
Average Revenue Per User (ARPU)
The average revenue generated by any user within a defined timeframe. Every user is
taken into account.
22
Conversion rate
The percentage of users that, having clicked the ad, go on to install the app.
Daily Active Users (DAU)
The number of unique users that have opened the app during a given day.
Event Conversion rate
The ratio of users that triggered a specific event at least once.
Events Per User
This is the number of times a specific event was triggered by a user within a defined
timeframe.
Monthly Active Users (MAU)
The number of unique users that have opened the app during a given 30 day period.
Time to first Event (TTFE)
The time that it takes for a user to trigger a specific event for the first time.
One Time Users (OTU)
The ratio of users that only opened and used the app on the day of installation.
Retention (30 day)
The 30 day retention is the rate of users that downloaded the app and are still using it
after a month. To be considered retained, a user must have opened the app within the
last 7 days of the 30 day timeframe.
User Lifetime
The length of time that a user is actively using an app. Lifetime ends when a user
stops using an app. For more meaningful data we deduct one time users from the
average.
23