Basic Setup

Example app

There is an example app inside the example directory .

Basic integration

We will describe the steps to integrate the Adtrace SDK into your React Native project. You can use any text editor or IDE for React Native development. There are no assumptions made regarding development environment.

Add sdk into your project

First, download the library from npm:

$ npm install react-native-adtrace --save

or

$ yarn add react-native-adtrace

For iOS app make sure to go to ios folder and install Cocoapods dependencies:

$ cd ios && pod install

After this Adtrace SDK should be successfully added to your app.

Integrate the SDK into your app

You should use the following import statement on top of your .js file

import { AdTrace, AdTraceEvent, AdTraceConfig } from 'react-native-adtrace';

In your App.js file, add the following code to initialize the Adtrace SDK:

constructor(props) {
    super(props);
    const adtraceConfig = new AdTraceConfig("{YourAppToken}", AdTraceConfig.EnvironmentSandbox);
    AdTrace.create(adtraceConfig);
}

componentWillUnmount() {
  AdTrace.componentWillUnmount();
}

Replace {YourAppToken} with your app token. You can find this in your panel.

Depending on whether you build your app for testing or for production, you must set the environment with one of these values:

AdTraceConfig.EnvironmentSandbox
AdTraceConfig.EnvironmentProduction

Important

This value should be set to AdTraceConfig.EnvironmentSandbox if and only if you or someone else is testing your app. Make sure to set the environment to AdTraceConfig.EnvironmentProduction just before you publish the app. Set it back to AdTraceConfig.EnvironmentSandbox when you start developing and testing it again.

We use this environment to distinguish between real traffic and test traffic from test devices. It is very important that you keep this value meaningful at all times!

Adtrace logging

You can increase or decrease the amount of logs you see in tests by calling setLogLevel on your AdTraceConfig instance with one of the following parameters:

adtraceConfig.setLogLevel(AdTraceConfig.LogLevelVerbose);   // enable all logging
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelDebug);     // enable more logging
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelInfo);      // the default
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelWarn);      // disable info logging
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelError);     // disable warnings as well
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelAssert);    // disable errors as well
adtraceConfig.setLogLevel(AdTraceConfig.LogLevelSuppress);  // disable all logging

Adtrace project settings

Once the Adtrace SDK has been added to your app, certain tweaks are going to be performed so that the Adtrace SDK can work properly. Below you can find a description of every additional thing that the Adtrace SDK performs after you've added it to your app and what needs to be done by you in order for Adtrace SDK to work properly.

Android permissions

The Adtrace SDK by default adds two permissions to your app's AndroidManifest.xml file:

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

The INTERNET permission might be needed by our SDK at any point in time. The ACCESS_WIFI_STATE permission is needed by the Adtrace SDK if your app is not targeting the Google Play Store and doesn't use Google Play Services. If you are targeting the Google Play Store and you are using Google Play Services, the Adtrace SDK doesn't need this permission and, if you don't need it anywhere else in your app, you can remove it.

Add permission to gather Google advertising ID

If you are targeting Android 12 and above (API level 31), you need to add the com.google.android.gms.AD_ID permission to read the device's advertising ID. Add the following line to your AndroidManifest.xml to enable the permission.

<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

For more information, see Google's AdvertisingIdClient.Info documentation.

Google Play Services

Since August 1, 2014, apps in the Google Play Store must use the Google Advertising ID to uniquely identify devices. To allow the Adtrace SDK to use the Google Advertising ID, you must integrate Google Play Services.

In order to do this, open your app's build.gradle file and find the dependencies block. Add the following line:

implementation 'com.google.android.gms:play-services-analytics:18.0.1'

note

The version of the Google Play Services library that you're using is not relevant to the Adtrace SDK, as long as the analytics part of the library is present in your app. In the example above, we just used the most recent version of the library at the time of writing.

To check whether the analytics part of the Google Play Services library has been successfully added to your app so that the Adtrace SDK can read it properly, you should start your app by configuring the SDK to run in sandbox mode and set the log level to verbose. After that, track a session or some events in your app and observe the list of parameters in the verbose logs which are being read once the session or event has been tracked. If you see a parameter called gps_adid in there, you have successfully added the analytics part of the Google Play Services library to your app and our SDK is reading the necessary information from it.

In case you encounter any issue with attempts to read Google Advertising Identifier, feel free to open an issue in our GitHub repository or contact our support.

Proguard settings

If you are using Proguard, add these lines to your Proguard file:

-keep class io.adtrace.sdk.** { *; }
-keep class com.google.android.gms.common.ConnectionResult {
    int SUCCESS;
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient {
    com.google.android.gms.ads.identifier.AdvertisingIdClient$Info getAdvertisingIdInfo(android.content.Context);
}
-keep class com.google.android.gms.ads.identifier.AdvertisingIdClient$Info {
    java.lang.String getId();
    boolean isLimitAdTrackingEnabled();
}
-keep public class com.android.installreferrer.** { *; }

Install referrer

In order to correctly attribute an install of your Android app to its source, Adtrace needs information about the install referrer. This can be obtained by using the Google Play Referrer API or by catching the Google Play Store intent with a broadcast receiver.

Important

The Google Play Referrer API is newly introduced by Google with the express purpose of providing a more reliable and secure way of obtaining install referrer information and to aid attribution providers in the fight against click injection. It is strongly advised that you support this in your application. The Google Play Store intent is a less secure way of obtaining install referrer information. It will continue to exist in parallel with the new Google Play Referrer API temporarily, but it is set to be deprecated in the future.

Google Play Referrer API

In order to support this, add the following line to your app's build.gradle file:

implementation 'com.android.installreferrer:installreferrer:2.2'

installreferrer library is part of Google Maven repository, so in order to be able to build your app, you need to add Google Maven repository to your app's build.gradle file if you haven't added it already:

allprojects {
    repositories {
        jcenter()
        maven {
            url "https://maven.google.com"
        }
    }
}

Also, make sure that you have paid attention to the Proguard settings chapter and that you have added all the rules mentioned in it, especially the one needed for this feature:

-keep public class com.android.installreferrer.** { *; }

Google Play Store intent

The Google Play Store INSTALL_REFERRER intent should be captured with a broadcast receiver. The Adtrace install referrer broadcast receiver is added to your app by default. For more information, you can check our native Android SDK README. You can see this in the AndroidManifest.xml file which is part of our React Native plugin:

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

Please bear in mind that, if you are using your own broadcast receiver which handles the INSTALL_REFERRER intent, you don't need to add the Adtrace broadcast receiver to your manifest file.

Huawei Referrer API

As of v2.+, the Adtrace SDK supports install tracking on Huawei devices with Huawei App Gallery version 10.4 and higher. for more information see how to use oaid plugin in react native.

iOS frameworks

Select your project in the Project Navigator. On the left hand side of the main view, select your target. In the tab Build Phases, expand the group Link Binary with Libraries. On the bottom of that section click on the + button. Select below-mentioned frameworks and make sure to change the Status of frameworks to Optional. Adtrace SDK uses these frameworks with following purpose:

• iAd.framework - to support Apple Search Ads campaigns
• AdServices.framework - to support Apple Search Ads campaigns
• AdSupport.framework - to read iOS Advertising ID (IDFA) value
• CoreTelephony.framework - to read MCC and MNC information
• StoreKit.framework - to communicate with SKAdNetwork framework
• AppTrackingTransparency.framework - to ask for user's consent to be tracked and obtain status of that consent

AppTrackingTransparency framework

note

This feature exists only in iOS platform.

For each package sent, the Adtrace backend receives one of the following four (4) states of consent for access to app-related data that can be used for tracking the user or the device:

• Authorized
• Denied
• Not Determined
• Restricted

After a device receives an authorization request to approve access to app-related data, which is used for user device tracking, the returned status will either be Authorized or Denied.

Before a device receives an authorization request for access to app-related data, which is used for tracking the user or device, the returned status will be Not Determined.

If authorization to use app tracking data is restricted, the returned status will be Restricted.

The SDK has a built-in mechanism to receive an updated status after a user responds to the pop-up dialog, in case you don't want to customize your displayed dialog pop-up. To conveniently and efficiently communicate the new state of consent to the backend, Adtrace SDK offers a wrapper around the app tracking authorization method described in the following chapter, App-tracking authorization wrapper.

App-tracking authorisation wrapper

note

This feature exists only in iOS platform.

Adtrace SDK offers the possibility to use it for requesting user authorization in accessing their app-related data. Adtrace SDK has a wrapper built on top of the requestTrackingAuthorizationWithCompletionHandler method, where you can as well define the callback method to get information about a user's choice. Also, with the use of this wrapper, as soon as a user responds to the pop-up dialog, it's then communicated back using your callback method. The SDK will also inform the backend of the user's choice. Integer value will be delivered via your callback method with the following meaning:

• 0: ATTrackingManagerAuthorizationStatusNotDetermined
• 1: ATTrackingManagerAuthorizationStatusRestricted
• 2: ATTrackingManagerAuthorizationStatusDenied
• 3: ATTrackingManagerAuthorizationStatusAuthorized

To use this wrapper, you can call it as such:

Adtrace.requestTrackingAuthorizationWithCompletionHandler(function(status) {
    switch (status) {
        case 0:
            // ATTrackingManagerAuthorizationStatusNotDetermined case
            break;
        case 1:
            // ATTrackingManagerAuthorizationStatusRestricted case
            break;
        case 2:
            // ATTrackingManagerAuthorizationStatusDenied case
            break;
        case 3:
            // ATTrackingManagerAuthorizationStatusAuthorized case
            break;
    }
});

Before calling the method, make sure that your iOS app's Info.plist contains an entry for NSUserTrackingUsageDescription key. In absence of that key and usage of this method, app will crash.

Get current authorisation status

To get the current app tracking authorization status you can call getAppTrackingAuthorizationStatus method of Adtrace class that will return one of the following possibilities:

• 0: The user hasn't been asked yet
• 1: The user device is restricted
• 2: The user denied access to IDFA
• 3: The user authorized access to IDFA
• -1: The status is not available

SKAdNetwork framework

If you have implemented the Adtrace iOS SDK v2.+ or above and your app is running on iOS 14 and above, the communication with SKAdNetwork will be set on by default, although you can choose to turn it off. When set on, Adtrace automatically registers for SKAdNetwork attribution when the SDK is initialized. If events are set up in the panel to receive conversion values, the Adtrace backend sends the conversion value data to the SDK. The SDK then sets the conversion value. After Adtrace receives the SKAdNetwork callback data, it is then displayed in the panel.

In case you don't want the Adtrace SDK to automatically communicate with SKAdNetwork, you can disable that by calling the following method on configuration object:

adtraceConfig.deactivateSKAdNetworkHandling();

Update SKAdNetwork conversion value

You can use Adtrace SDK wrapper method updateConversionValue to update SKAdNetwork conversion value for your user:

AdTrace.updateConversionValue(6);

Conversion value updated callback

You can register callback to get notified each time when Adtrace SDK updates conversion value for the user.

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setConversionValueUpdatedCallbackListener(function(conversionValue) {
    console.log("Conversion value updated callback received");
    console.log("Conversion value: " + conversionValue.conversionValue);
  });

AdTrace.create(adtraceConfig);