Set up Adjust as an analytics platform

This article guides you on setting up Adjust as an analytics platform, allowing your game to report telemetry data directly to Adjust.

Prerequisites

note

Adjust supports multi-store packages through multiple app IDs under the same developer account. Create additional game apps in the Adjust dashboard and complete the configurations for additional game apps by repeating the following steps.

1. Set up your Adjust account and create a new app

Create an Adjust account.
From Adjust dashboard, click New app at the top right corner to create a new app.
Fill up the app information, then click Add app.

2. Get app token (ID)

From Adjust dashboard, go to AppView > All apps from the navigation bar on the left.
The app token is displayed next to the corresponding app name.

info

App token is a string that is different for iOS and Android.

3. [Optional] Create tracker URL

A tracker URL is only needed if your app is distributed through third-party stores (e.g. Samsung, Xiaomi, Huawei) instead of the Google Play Store.

The tracker token must be embedded in the APK to track organic installs and user behavior from those platforms.

caution

After creating a tracker URL, data will only be visible in the Adjust dashboard after more than 3 hours.

From Adjust dashboard, go to Campaign Lab > Custom links, and click New Link at the top right corner.
Select your app and click Next.
Enter a name for the link and click Quick create.
Once created, the tracker token is the 6 or more alphanumeric characters after the Adjust endpoint.

Integrate the Player Network SDK.

Step 1: Set up permissions and configurations

Android

User permissions

Adjust requires permissions to access the network and WiFi status.

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

receiver is used to track the source of installation. It is integrated into Player Network SDK, check the configuration in the SDK package.

<receiver android:name="com.adjust.sdk.AdjustReferrerReceiver" android:exported="true" >
  <intent-filter>
      <action android:name="com.android.vending.INSTALL_REFERRER" />
  </intent-filter>
</receiver>

caution

Adjust does not provide any interface to manually control the collection of the Mac address. It only relies on the ACCESS_WIFI_STATE permission to collect the Mac address.
As the compliance requirements do not allow the collection of Mac addresses, Player Network SDK does not apply for the WiFi status permission for Adjust by default. At the same time, all plugins in Player Network SDK do not apply for this permission by default.

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Configurations

Add the following configurations in the INTLConfig.ini file:

[Adjust Debug Mode]
DEBUG_CHANNEL = Adjust
[Android LifeCycle]
LIFECYCLE = Adjust
[Adjust Configurations]
ADJUST_OPEN_DEEPLINK_ENABLE = 0
ADJUST_APP_TOKEN_ANDROID = {ADJUST_APP_TOKEN_ANDROID}
ADJUST_REGISTER_EVENT_TOKEN_ANDROID = {REGISTER_TOKEN}
ADJUST_LOGIN_EVENT_TOKEN_ANDROID = {LOGIN_TOKEN}
ADJUST_APPSECRET_ANDROID = {ADJUST_SECRET_ID}
ADJUST_INFO1_ANDROID = {INFO_01}
ADJUST_INFO2_ANDROID = {INFO_02}
ADJUST_INFO3_ANDROID = {INFO_03}
ADJUST_INFO4_ANDROID = {INFO_04}
ADJUST_SUB_DOMAIN = {ADJUST_SUBDOMAIN}
ADJUST_URL_STRATEGY_ANDROID = {ADJUST_URL_STRATEGY_ANDROID}
ADJUST_SIGNATURE_VERSION_ANDROID = {ADJUST_SIGNATURE_VERSION_ANDROID}
ADJUST_CHANNEL_START_EVENT_TOKEN_ANDROID = {ADJUST_CHANNEL_START_EVENT_TOKEN_ANDROID}

Set DEBUG_CHANNEL to Adjust to enable the Adjust debug mode.
Add Adjust to LIFECYCLE. For more information, see SDK environment.
Use ADJUST_OPEN_DEEPLINK_ENABLE to enable or disable deep linking. The default value is 0, disable.
Replace {ADJUST_APP_TOKEN_ANDROID} with the Android App Token found from the Adjust dashboard.
[Optional] Create a registration event, and set {REGISTER_TOKEN} to the corresponding event token.
[Optional] Create a login event, and set {LOGIN_TOKEN} to the corresponding event token.
Use {ADJUST_SECRET_ID} to prevent SDK spoofing. This numeric value is supported by V4.12.0 or later versions of Adjust SDK.
{INFO_01}, {INFO_02}, {INFO_03}, {INFO_04} configurations are valid only after {ADJUST_SECRET_ID} is set. Follow the instructions in SDK Signature for the configuration.
Set {ADJUST_SUBDOMAIN} to the relay server that Adjust reports to.
Set {ADJUST_URL_STRATEGY_ANDROID} to Adjust data residency. For more information, see Adjust configurations.
Set {ADJUST_SIGNATURE_VERSION_ANDROID} to configure the Adjust signature version, where the value 1 indicates v1 signature and 2 indicates v2 signature.
Replace {ADJUST_CHANNEL_START_EVENT_TOKEN_ANDROID} with the Adjust custom startup event token.

iOS

Configurations

Add the following configurations in the INTLConfig.ini file:

[Adjust Debug Mode]
DEBUG_CHANNEL = Adjust
[Adjust Configurations]
ADJUST_OPEN_DEEPLINK_ENABLE = 0
ADJUST_APP_TOKEN_IOS = {ADJUST_APP_TOKEN_IOS}
ADJUST_REGISTER_EVENT_TOKEN_IOS = {REGISTER_TOKEN}
ADJUST_LOGIN_EVENT_TOKEN_IOS = {LOGIN_TOKEN}
ADJUST_APPSECRET_IOS = {ADJUST_SECRET_ID}
ADJUST_INFO1_IOS = {INFO_01}
ADJUST_INFO2_IOS = {INFO_02}
ADJUST_INFO3_IOS = {INFO_03}
ADJUST_INFO4_IOS = {INFO_04}
ADJUST_SUB_DOMAIN = {ADJUST_SUBDOMAIN}
ADJUST_URL_STRATEGY_IOS = {ADJUST_URL_STRATEGY_IOS}
ADJUST_SIGNATURE_VERSION_IOS = {ADJUST_SIGNATURE_VERSION_IOS}
ADJUST_CHANNEL_START_EVENT_TOKEN_IOS = {ADJUST_CHANNEL_START_EVENT_TOKEN_IOS}

Set DEBUG_CHANNEL to Adjust to enable the Adjust debug mode.
Use ADJUST_OPEN_DEEPLINK_ENABLE to enable or disable deep linking. The default value is 0, disable.
Replace {ADJUST_APP_TOKEN_IOS} with the iOS App Token found from the Adjust dashboard.
[Optional] Create a registration event, and set {REGISTER_TOKEN} to the corresponding event token.
[Optional] Create a login event, and set {LOGIN_TOKEN} to the corresponding event token.
Use {ADJUST_SECRET_ID} to prevent SDK spoofing. It is a numeric value.
{INFO_01}, {INFO_02}, {INFO_03}, {INFO_04} configurations are valid only after {ADJUST_SECRET_ID} is set. Contact Adjust account manager, kchuang from Tencent to get the INFO values.
Set {ADJUST_SUBDOMAIN} to the relay server that Adjust reports to.
Set {ADJUST_URL_STRATEGY_IOS} to Adjust data residency. For more information, see Adjust configurations.
Set {ADJUST_SIGNATURE_VERSION_IOS} to configure the Adjust signature version, where the value 1 indicates v1 signature and 2 indicates v2 signature.
Replace {ADJUST_CHANNEL_START_EVENT_TOKEN_IOS} with the Adjust custom startup event token.

[Optional] Export Xcode with Unity

When using Unity to export Xcode projects, configure the .projmods file.

note

Games need to check the configurations written in INTLCoreKit.projmods.

{
    "group": "INTL",
    "libs": ["libz.tbd", "libsqlite3.tbd"],
    "frameworks": ["AdSupport.framework", "iAd.framework", "CoreTelephony.framework", "SystemConfiguration.framework"],
    "files": [],
    "folders": [],
    "excludes": [],
    "headerpaths":[],
    "build_settings":{},
    "system_capabilities": {},
    "Info.plist":{}
}

[Optional] Deep Linking

Add the following code to AppDelegate.m:

- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray * _Nullable))restorationHandler

info

Adjust automatically supports deferred deep linking. If you want to handle deferred deep link content in your app, refer to the official Adjust guide.

Step 2: Add tracker token to APK

info

This step is only required if you want to track organic installs and user behavior from third-party app stores (e.g. Samsung, Xiaomi, Huawei).

The Adjust tracker attributes user behaviors to the source campaign. A unique tracker token is automatically generated by Adjust for every tracker. For more information, see Adjust links.

caution

The Adjust V2 signature must be supported.

Customize the Gradle plugin and create a task.

project.afterEvaluate {
    ChannelMaker channelMaker = project.tasks.create("assemble${variantName}Channels", ChannelMaker);
    channelMaker.targetProject = project;
    channelMaker.variant = variant;
    channelMaker.setup();

    // task add dependencies
    if (variant.hasProperty('assembleProvider')) {
        channelMaker.dependsOn variant.assembleProvider.get()
    } else {
        channelMaker.dependsOn variant.assemble
    }
}   

Process the tracker token logic in the task.

caution

The data is big-endian.
The protocol header is fixed new byte []-106.

Get the input data.

// get the input data
byte[] encode() throws IOException {
    ByteArrayOutputStream out = new ByteArrayOutputStream();
    // write protocol header
    out.write(new byte[]{-6, -106});
    String s = "adjustTrackerToken=${tracek_token}";
    byte[] bytes = s.getBytes("UTF-8");
    out.write(new ZipShort(bytes.length).getBytes());
    out.write(bytes);
    return out.toByteArray();
}

public final class ZipShort implements Cloneable {
    private int value;

    public ZipShort(byte[] bytes) {
        this(bytes, 0);
    }

    public ZipShort(byte[] bytes, int offset) {
        this.value = bytes[offset + 1] << 8 & '\uff00';
        this.value += bytes[offset] & 255;
    }

    public ZipShort(int value) {
        this.value = value;
    }

    public boolean equals(Object o) {
        if (o != null && o instanceof ZipShort) {
            return this.value == ((ZipShort)o).getValue();
        } else {
            return false;
        }
    }

    public byte[] getBytes() {
        byte[] result = new byte[]{(byte)(this.value & 255), (byte)((this.value & '\uff00') >> 8)};
        return result;
    }

    public int getValue() {
        return this.value;
    }

    public int hashCode() {
        return this.value;
    }
}

Write the data to APKSigningBlock with blockid 0x71717874.

Build the Gradle package using ./gradlew assemble${variantName}Channels.
In the log view, enter set default tracker : ${tracker_token} to verify whether the gradle packaging is successful.

Step 3: Configure event reporting

Automatically logged events

If ANALYTICS_AUTH_REPORT_ENABLE is enabled in the INTLConfig.ini file and Adjust’s registration and login tokens are set, Player Network SDK will automatically report the following events:

completed_registration: When a user logs in to the game for the first time
login: When a user logs in to the game subsequently

Manually logged events

1. Create new events

From Adjust dashboard, select your app.
Navigate to Events and click Add event in the top right corner.
Enter an event name and click Add event.

2. Get event token (ID)

From Adjust dashboard, select your app.
Navigate to Events—each event displays its token in the Token column.

note

After configuring an event in the dashboard, use its assigned event token in your code for reporting.

3. Set event uniqueness

Event uniqueness ensures that a single device only counts the unique event once.

From Adjust dashboard, select your app.
Navigate to Events, locate your event, and click the edit icon.
Check "This is a unique event" and save changes.

For more information, refer to Adjust Events.

To use Adjust partner parameters, add parameters in the extraJson field:
"{\"isPartnerParameters\":true}"
If the extraJson field is empty, or isPartnerParameters is set to false, the reporting parameters will be set in Adjust callback_params.
To track events, enter the event token for each EventName. For more information, see Adjust Event tracking.

For more information, see Analytics.

Funnel events

note

Supported since Player Network SDK V1.20.

In INTLConfig.ini, add ADJUST_REPORT_FUNNEL_EVENTS_TOKEN_IOS (for iOS platforms) and ADJUST_REPORT_FUNNEL_EVENTS_TOKEN_ANDROID (for Android platforms) configurations. Android platforms add the funnel events to be reported to the Adjust channel and the corresponding tokens in the format event1:token1,event2:token....

[Adjust]
ADJUST_REPORT_FUNNEL_EVENTS_TOKEN_IOS = app_launch:your_token,confirm_login_channel:your_token,channel_auth_success:your_token,login_auth_success:your_token,query_complicance:your_token,select_region_and_age:your_token,agree_privacy_policy:your_token,privacy_auth_sucess:your_token,show_server_list:your_token,submit_area:your_token,confirm_area:your_token,connect_svr_success:your_token,show_user_agreement:your_token,finish_user_agreement:your_token,check_for_updates:your_token,download_updates:your_token,unzip_files:your_token,complete_updates:your_token,show_enter_game:your_token,click_into_game:your_token,enter_lobby_success:your_token,authentication:your_token,pull_up_the_list_of_goods:your_token,pull_up_price_list:your_token,start_order:your_token,successful_order:your_token,start_payment:your_token,successful_payment:your_token,start_delivery:your_token,successful_delivery:your_token,register_success:your_token
ADJUST_REPORT_FUNNEL_EVENTS_TOKEN_ANDROID = app_launch:your_token,confirm_login_channel:your_token,channel_auth_success:your_token,login_auth_success:your_token,query_complicance:your_token,select_region_and_age:your_token,agree_privacy_policy:your_token,privacy_auth_sucess:your_token,show_server_list:your_token,submit_area:your_token,confirm_area:your_token,connect_svr_success:your_token,show_user_agreement:your_token,finish_user_agreement:your_token,check_for_updates:your_token,download_updates:your_token,unzip_files:your_token,complete_updates:your_token,show_enter_game:your_token,click_into_game:your_token,enter_lobby_success:your_token,authentication:your_token,pull_up_the_list_of_goods:your_token,pull_up_price_list:your_token,start_order:your_token,successful_order:your_token,start_payment:your_token,successful_payment:your_token,start_delivery:your_token,successful_delivery:your_token,register_success:your_token

Adding the Adjust channel to the ANALYTICS_REPORT_FUNNEL_CHANNEL configuration in INTLConfig.ini, Player Network SDK will synchronize the funnel events to the Adjust channel.

[ANALYTICS]
ANALYTICS_REPORT_FUNNEL_CHANNEL = Adjust

See Query data to view the reported events.

Step 4: Initialize Analytics

Unity
Unreal Engine

Initialize the Analytics module, then call ReportEvent to start Adjust data reporting.

Data reporting acceptance

References

Data dimensions

Adjust events:

InstallEvent (UnInstallEvent/ReInstallEvent)
InAppEvent

For more information about event data properties, see Event and session callbacks.

View reported events in the console

caution

Events are not reported in realtime, with a latency of 1 hour or more.

From Adjust dashboard, click Installs.
View all reported events in the statistics table.

View reported events in Sandbox Mode

note

The latency in Sandbox Mode is about 10 minutes.

Configuration

To report data to Adjust Sandbox Mode:

Include Adjust for the DEBUG_CHANNEL configured in INTLConfig.ini.
Set LOG_LEVEL = 1 or LOG_LEVEL = 0 in INTLConfig.ini.

Set LOG_LEVEL = 3 when releasing the game to report data to Adjust production environment.

To report to Adjust production environment, remove Adjust from the DEBUG_CHANNEL configured in INTLConfig.ini.

The log file after successfully reporting data to Sandbox Mode is as follows:

Image: Adjust Sandbox

Viewing Your Device Data in Testing Console

From Adjust dashboard, go to Testing console.
Enter your device IDFA to view device data.

Image: Input ad ID

note

On iOS 14+, App Tracking Transparency (ATT) permission must be granted before initializing the Adjust SDK to view device data in the Testing console.

Adjust registers each device only once for installs. To test multiple installs or unique events on the same device, open Testing console and click Forget Device. This clears all device data for this app, allows new test events to be recorded.

Find Your Device Advertising ID

Android
iOS

Select Settings > Google > Ads on the device to view the ad ID.

A third-party tool must be used to view the Apple IDFA. Many apps that provide this function are available on the App Store. Examples include My Device ID by AppsFlyer and Adjust Insights, as shown below:

Image: AppsFlyer My Device ID

Open the app on the device and initialize Player Network SDK, and upload the event to get the gps_adid string in the control panel.

View reported data

Configure INTLConfig.ini to enable Sandbox mode data reporting for the client.
From Adjust dashboard, click Installs.
Under Data configuration, check Environment. The Environment dropdown will appear.
Select Sandbox environment to view reported events in sandbox mode.

Acceptance use case 1

Sub-function module: Reporting
Feature: Event Reporting
Test points: First login as guest, check Adjust login reporting
Prerequisites: Initialize Analytics module
Procedure or Input:
1. Log in as a guest for the first time
2. Log off
3. Log in again with the same account
4. In the console, export data and view reported events
Expected output: Information reported successfully.
1. In the console, view:
  1. Registration event reported for the first guest login (adjust_complete_registration): Reported qty+1
  2. Login event reported when the user logs in again with the same account (adjust_login): Reported qty+1
2. Exported data verification: Contact [killuachen] to form a group for final confirmation:
  1. Registration event reported for the first guest login (adjust_complete_registration): Reported qty+1
  2. Login event reported when the user logs in again with the same account (adjust_login): Reported qty+1
  3. Player Network SDK OpenID is provided in the event parameters

Acceptance use case 2

Sub-function module: Reporting
Feature: Event Reporting
Test points: Non-first login from Facebook, check Adjust login reporting
Prerequisites: Initialize Analytics module
Procedure or Input:
1. Use Facebook to log in for the first time
2. Log off
3. Log in again with the same account
4. Export data and view reported events in the console
Expected output: Information reported successfully.
1. In the console, view:
  1. Registration event reported for the first guest login (adjust_complete_registration): Reported qty+1
  2. Login event reported when the user logs in again with the same account (adjust_login): Reported qty+1
2. Exported data verification: Contact [killuachen] to form a group for final confirmation
  1. Registration event reported for the first guest login (adjust_complete_registration): Reported qty+1
  2. Login event reported when the user logs in again with the same account (adjust_login): Reported qty+1
  3. Player Network SDK OpenID is provided in the event parameters

Acceptance use case 3

Sub-function module: Reporting
Feature: Event Reporting
Test points: First and subsequent login from Facebook, check Adjust login reporting
Prerequisites: Initialize Analytics module
Procedure or Input:
1. Use Facebook to log in for the first time
2. Log off
3. Log in again with the same account
4. Export data and view reported events in the console
Expected output: Information reported successfully.
1. In the console, view:
  1. Registration event reported for the first guest login (adjust_complete_registration): Reported qty+1
  2. Login event reported when the user logs in again with the same account (adjust_login): Reported qty+1
2. Export data verification:
  1. Registration event reported for the first guest login (adjust_complete_registration): Reported qty+1
  2. Login event reported when the user logs in again with the same account (adjust_login): Reported qty+1
  3. The Customer User ID and Player Network SDK OpenID are consistent

Acceptance use case 4

Sub-function module: Reporting
Feature: Event Reporting
Test points: Event information successfully reported by Adjust
Prerequisites: Initialize Analytics module
Procedure or Input:
1. Request Report Event
2. eventName = Report_Event, paramsDic-key1=k1, paramsDic-value1=v1, paramsDic-key2=k2, paramsDic-value2=v2, spChannels=Adjust
3. Install or uninstall the SDK and launch the game
4. View the report data and export the INSTALL data table
Expected output: Information reported successfully, check the following:
1. In the console, view:
  1. Custom events: Adjust can query custom Report_Event qty +1
  2. Install event: View reported INSTALL event qty +1 (only reported once if device information is not cleared)
2. Exported data verification: Contact [killuachen] to form a group for final confirmation:
  1. Custom events: Compare install_time={installed_at} of reported data (in the console or in exported data) to determine if this is the install time and if event_name={event_name} is the custom event.
  2. Install event: View reported Installs event qty+1 in the INSTALL data table (only reported once if device information is not cleared). activity_kind={activity_kind} adds an install.

Acceptance use case 5

Sub-function module: ReportRevenue
Feature: Adjust payment event reporting
Test points: Query report after requesting ReportRevenue (Adjust)
Prerequisite: Network connection is normal
Procedure or Input:
1. Request ReportRevenue
2. eventName = (customizable), spChannels = Adjust, Currency = USD, Revenue = 100
3. Adjust query reporting events
4. DD Platform query AnalyticsReportRevenue event
Expected output: Information reported successfully.
1. View ReportRevenue event +1 in the Adjust delivery data. The ReportRevenue (revenue) event amount +100.
2. Export data verification (2-4 hours): Export data contains income event and amount data.
3. DD Platform successfully queries the event reporting with methodName as AnalyticsReportRevenue and method_id=715.

Acceptance use case 6

Sub-function module: ReportRevenue
Feature: Adjust payment event reporting
Test points: Query report after requesting ReportRevenue in disconnected state (Adjust)
Prerequisite: Disconnected network status
Procedure or Input:
1. Request ReportRevenue
2. eventName = (customizable), spChannels = Adjust, Currency = USD, Revenue = 1000
3. Reconnect to the network
4. Adjust query reporting events
5. DD Platform query AnalyticsReportRevenue event
Expected output: Information reported successfully.
1. After reconnecting to the network
2. View the ReportRevenue event in Adjust delivery data +1, and the ReportRevenue (revenue) event amount +1000.
3. Export data verification (2-4 hours): Export data contains income events and amount data.
4. DD Platform successfully queries the event reporting with methodName as AnalyticsReportRevenue and method_id=715.

FAQ

The reported event must implement the token found on Adjust dashboard.
If initialization fails, the STAT_ADJUST_APP_TOKEN and ADJUST_INFO1 information of the Adjust project is incomplete.
Adjust supports the callback parameter and partner parameter.
For more information, see ReportEvent.
For an example of the integration, see Analytics.
It is recommended to enable Sandbox mode for Adjust event reporting. Data updates for the dashboard depend on the realtime performance of the background calculations. Data is usually updated in a few minutes, but can be updated on the next day in some cases. If the data is not updated after 30 minutes, check again the next day.

Error codes

For more information, see Adjust Help Center.

Prerequisites​

Step 1: Set up permissions and configurations​

Android​

iOS​

[Optional] Export Xcode with Unity​

Step 2: Add tracker token to APK​

Step 3: Configure event reporting​

Automatically logged events​

Manually logged events​

Funnel events​

Step 4: Initialize Analytics​

Data reporting acceptance​

References​

Data dimensions​

View reported events in the console​

View reported events in Sandbox Mode​

Acceptance use case 1​

Acceptance use case 2​

Acceptance use case 3​

Acceptance use case 4​

Acceptance use case 5​

Acceptance use case 6​

FAQ​

Error codes​

Prerequisites

Step 1: Set up permissions and configurations

Android

iOS

[Optional] Export Xcode with Unity

Step 2: Add tracker token to APK

Step 3: Configure event reporting

Automatically logged events

Manually logged events

Funnel events

Step 4: Initialize Analytics

Data reporting acceptance

References

Data dimensions

View reported events in the console

View reported events in Sandbox Mode

Acceptance use case 1

Acceptance use case 2

Acceptance use case 3

Acceptance use case 4

Acceptance use case 5

Acceptance use case 6

FAQ

Error codes