We constantly publish updates to our documentation, which may not yet be available in your language. For the most current information, use the English version.

for Marketers

Adjust migration guide

Moving to Adjust from another Mobile Measurement Partner is a straightforward process. Adjust offers support and guidance every step of the way, and a range of resources for you to refer to.

An infographic showing the steps you follow when you migrate to Adjust from another MMP.

Follow the instructions in this guide to complete the following migration steps:

Note:

If your plan includes dedicated support, you will receive workshops covering SDK integration, UA setup, data export/BI, Datascape/data analysis, and iOS campaign setup.

How does device import work?

The Adjust SDK treats users that you have before you implemented the Adjust SDK as new users. This happens as soon as they open the app for the first time. This means that existing users are reported as new installs. So, if you are using any other analytics or reporting tools, or comparing App Store or Google Play numbers, you’ll see a mismatch between the total number of installs reported.

To avoid this mismatch, you can import users to Adjust so that Adjust knows not to report those users as new installs. Adjust reports those installs as new sessions and it won’t count towards overall installs. You can still see the activity and performance of those users, for example, retention and completed events, if you run re-engagement campaigns as those users can be re-attributed to a new traffic source.

1. Set up your app in Adjust

Before you can import your historical data, you need to set up your app in AppView. All historic data is imported against your Adjust app token.

Follow the instructions in the app setup guide.
Once you finish setting up your app, copy your app token.

2. Integrate and test the Adjust SDK

Warning:

Don't submit your app(s) to an app store before Adjust completes your data import. This causes Adjust to record existing users as new users.

SDK documentation is available in the Developer section of the help center. While you're configuring your app to work with the Adjust SDK, make sure you put the SDK in sandbox mode and turn the logging up to verbose to capture as much information as possible. If you have any questions about SDK integration, reach out to your Adjust representative or support@adjust.com.

Adjust offers a testing console and a Device API to make testing easy. Use these tools to analyze the data the SDK sends to Adjust's servers.

3. Export your historical data

Once you've set up your app in AppView, you need to create an import file containing your historic data. Export your information from your previous Mobile Measurement Partner or your Business Intelligence system and format your file as follows.

File format

Your file must be a CSV (Comma Separated Values) file that is:

UTF-8 encoded.
Comma-delimited
Qualified with double quotes (").

File name

Your CSV file name must contain the following information in lower case:

The app token you saved in step 1.
The name of the target operating system (e.g. ios or android).
The type of device ID that is contained in the file.

You must provide a file for each device ID type.

<app_token>_<os_name>_<device_id_type>.csv

Device ID types

The following device ID types are available:

For iOS:

idfa
idfv

For Android devices targeting the Google Play Store:

gps_adid
android_id

For Android devices targeting the Amazon app store:

fire_adid
android_id

Example

This example demonstrates the file name you should use for data with the following properties:

Relating to an app with an Adjust app token of abc123.
For Android devices.
Identified by the gps_adid device ID type.

abc123_android_gps_adid.csv

Fields

Important:

Any double quotes (") in your CSV must be escaped. To do this, enclose quoted fields in another set of double quotes like this: ""High spenders"".

Your CSV file must contain the following fields, in this order:

Field	Required or optional	Example value	Notes
`device_id`	Required	`B1CDA5FE-BEBA-48ED-AD0F-27AE62BF82D8`	Dashes are optional. Accepted `device_id` types: `android_id` (case-insensitive) `external_device_id` (case-sensitive) `gps_adid` (Google Advertising ID, case-insensitive) `fire_adid` (case-insensitive) `idfa` (case-insensitive) `idfv` (case-insensitive)
`created_at`	Optional	`1586391845`	Unix install timestamp as an integer, specified in seconds. If this field isn't populated in the import file, the value is automatically populated with the timestamp of the import.
`network`	Required	`Imported Devices`	Imported data should be put in a separate network to avoid confusion with live Adjust datasets. See the network mapping table for more information about how to structure this information.
`campaign`	Optional	`ironsource`
`adgroup`	Optional	`ironsource_ios_us`
`creative`	Optional	Ad Group 1

If you don't have information for one or more of the optional fields, insert an empty field. Each row must contain the same number of fields as the header row.

Network mapping

It is important that you import your historical data under a placeholder network called "Imported Devices" as shown in the table below. All of the returning users are placed under this placeholder and your data remains clean. This hardcoded placeholder means that Adjust can differentiate between traffic coming from existing users, that is, users from before the Adjust SDK implementation, and new users that should be attributed to an active campaign.

If you import users under the same default network partner, you could see issues when you analyze certain KPIs and that could mislead your analysis of campaigns and app performance.

Use the full structure below if you want to drill down through your existing campaign data to three sublevels:

Previous system value	Adjust import CSV value	Notes
—	`network`	Hardcode this value to `Imported Devices`.
Network name	`campaign`
Campaign name	`adgroup`
Ad group name	`creative`

The granularity (network, campaign, ad group) of imported devices is not mandatory and is there in case you want to maintain that data.

Example

Here is a template with a header row and values:

device_id,created_at,network,campaign,adgroup,creative
<device_id>,<created_at>,Imported Devices,<network>,<campaign>,<adgroup>

Populate <device_id>, <created_at>, <network>, <campaign>, and <adgroup> with values from your previous system. For example:

device_id,created_at,network,campaign,adgroup,creative
B1CDA5FE-BEBA-48ED-AD0F-27AE62BF82D8,1586391845,Imported Devices,ironsource,ironsource_ios_us,Ad Group 1

4. Import your data into Adjust

Once you've exported your data and verified the files meet the above criteria, upload the files to a secure location and send it to your Adjust representative. Adjust's technical team imports your CSV files and checks the data over to make sure everything looks right. Your Adjust representative will contact you when your import is complete.

Note:

Imported users don't automatically appear in Datascape reporting. They show up when they start a session in your app after you've released an update containing the Adjust SDK.

5. Release your app

Once your developers confirm they've integrated the SDK and your Adjust representative confirms they've imported your data, you can submit a new version of your app to the store. Check your app statistics to verify that existing users and new installs are being recorded as you expect.

6. Set up your campaigns

Follow the campaign setup guides to set up campaigns with network partners and self-attributing networks. If you need support setting up a campaign, provide a list of partners to your Adjust representative.

If your plan includes dedicated support, your Adjust representative will arrange a workshop to tak you through:

The types of campaigns you can record
The levels of information you can receive
How to create a campaign link
Adjust's attribution methodology
How to set up an iOS 14+ campaign

After this workshop, you'll be ready to reach out to your network partners for campaign configuration.

7. Update your campaign links

Note:

Networks must not begin testing until after the version of your app with the Adjust SDK integrated is live in the app store.

Once you've configured your campaigns, send your Adjust campaign links to your network partners so they can test the new links and update their settings.

8. Explore the new Adjust suite

That's it! It's time to start using the new Adjust suite. Check out the help center for guides on:

How to analyze your data in Datascape.
How to set up your iOS campaigns with the Adjust Conversion Hub.
How to pull reports with the Report Services API.
How to receive raw data exports through server callbacks and cloud storage uploads.

If you need further advice or clarification, contact your account manager or reach out to support@adjust.com.