react-native-wisetrack

Summary

This is the React Native SDK of WiseTrack™. You can read more about WiseTrack™ at [wisetrack.io].

Table of contents

* Example app
* Basic integration
* Get the SDK
* Integrate the SDK into your app
* WiseTrack logging
* WiseTrack project settings
* Android permissions
* Google Play Services
* Proguard settings
* Install referrer
* Google Play Referrer API
* Google Play Store intent
* Huawei Referrer API
* iOS frameworks
* Additional features
* AppTrackingTransparency framework
* App-tracking authorisation wrapper
* Get current authorisation status
* Check for ATT status change
* SKAdNetwork framework
* Update SKAdNetwork conversion value
* Conversion value updated callback
* Event tracking
* Revenue tracking
* Revenue deduplication
* Callback parameters
* Partner parameters
* Callback identifier
* Subscription tracking
* Session parameters
* Session callback parameters
* Session partner parameters
* Delay start
* Attribution callback
* Session and event callbacks
* Disable tracking
* Offline mode
* Event buffering
* GDPR right to be forgotten
* Third-party sharing
* Disable third-party sharing
* Enable third-party sharing
* Measurement consent
* SDK signature
* Background tracking
* Device IDs
* iOS advertising identifier
* Google Play Services advertising identifier
* Amazon advertising identifier
* WiseTrack device identifier
* Set external device ID
* Push token
* Track additional device identifiers
* Pre-installed trackers
* Deep linking
* Standard deep linking
* Deferred deep linking
* Reattribution via deep links
* Data residency
* COPPA compliance
* Play Store Kids Apps
* License

Example app

There is an example app inside the [example directory][example].

Basic integration

We will describe the steps to integrate the WiseTrack 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.

$3

First, download the library from npm:

``
$ npm install react-native-wisetrack --save
`

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

`
$ cd ios && pod install
`

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

$3

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

`javascript
import { WiseTrack, WiseTrackEvent, WiseTrackConfig } from 'react-native-wisetrack';
`

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

`javascript
constructor(props) {
super(props);
const wisetrackConfig = new WiseTrackConfig("{YourAppToken}", WiseTrackConfig.EnvironmentSandbox);
WiseTrack.create(wisetrackConfig);
}

componentWillUnmount() {
WiseTrack.componentWillUnmount();
}
`

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

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

`
WiseTrackConfig.EnvironmentSandbox
WiseTrackConfig.EnvironmentProduction
`

Important: This value should be set to WiseTrackConfig.EnvironmentSandbox if and only if you or someone else is testing your app. Make sure to set the environment to WiseTrackConfig.EnvironmentProduction just before you publish the app. Set it back to WiseTrackConfig.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!

$3

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

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

$3

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

$3

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

`xml


`

The INTERNET permission might be needed by our SDK at any point in time. The ACCESS_NETWORK_STATE permission is needed for reading type of network device is connected to.

#### 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. This will be done automatically by the WiseTrack SDK for you:

`xml

`

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

In case you don't want this permission to be part of your app, you can remove it by adding following line to your AndroidManifest.xml file:

`xml

`

$3

Since August 1, 2014, apps in the Google Play Store must use the [Google Advertising ID][google-ad-id] to uniquely identify devices. To allow the WiseTrack SDK to use the Google Advertising ID, you must integrate [Google Play Services][google-play-services].

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

`gradle
implementation 'com.google.android.gms:play-services-ads-identifier:18.0.1'
`

Note: The version of the Google Play Services library that you're using is not relevant to the WiseTrack 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 WiseTrack 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 write an email to support@wisetrack.com.

$3

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

`
-keep class com.wisetrack.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.* { ; }
`

$3

In order to correctly attribute an install of your Android app to its source, WiseTrack 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 future.

#### Google Play Referrer API

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

`gradle
compile '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:

`gradle
allprojects {
repositories {
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.* { ; }
`

This feature is supported if you are using the WiseTrack SDK v4.12.0 or above.

#### Google Play Store intent

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

`xml
android:exported="true" >




`

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 WiseTrack broadcast receiver to your manifest file. You can remove it, but inside your own receiver add the call to the WiseTrack broadcast receiver as described in our [Android guide][broadcast-receiver-custom].

#### Huawei Referrer API

As of v4.22.0, the WiseTrack SDK supports install tracking on Huawei devices with Huawei App Gallery version 10.4 and higher. No additional integration steps are needed to start using the Huawei Referrer API.

$3

Select your project in the Project Navigator. In 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. WiseTrack SDK uses these frameworks with following purpose:

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

Additional features

You can take advantage of the following features once the WiseTrack SDK is integrated into your project.

$3

Note: This feature exists only in iOS platform.

For each package sent, the WiseTrack 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, WiseTrack SDK offers a wrapper around the app tracking authorization method described in the following chapter, App-tracking authorization wrapper.

$3

Note: This feature exists only in iOS platform.

WiseTrack SDK offers the possibility to use it for requesting user authorization in accessing their app-related data. WiseTrack 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:

`js
WiseTrack.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.

$3

Note: This feature exists only in iOS platform.

To get the current app tracking authorization status you can call getAppTrackingAuthorizationStatus method of WiseTrack 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

$3

Note: This feature exists only in iOS platform.

In cases where you are not using WiseTrack app-tracking authorization wrapper, WiseTrack SDK will not be able to know immediately upon answering the dialog what is the new value of app-tracking status. In situations like this, if you would want WiseTrack SDK to read the new app-tracking status value and communicate it to our backend, make sure to make a call to this method:

`js
WiseTrack.checkForNewAttStatus();
`

$3

Note: This feature exists only in iOS platform.

If you have implemented the WiseTrack iOS SDK v4.23.0 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, WiseTrack automatically registers for SKAdNetwork attribution when the SDK is initialized. If events are set up in the WiseTrack dashboard to receive conversion values, the WiseTrack backend sends the conversion value data to the SDK. The SDK then sets the conversion value. After WiseTrack receives the SKAdNetwork callback data, it is then displayed in the dashboard.

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

`js
wisetrackConfig.deactivateSKAdNetworkHandling();
`

$3

Note: This feature exists only in iOS platform.

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

`js
WiseTrack.updateConversionValue(6);
`

$3

Note: This feature exists only in iOS platform.

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

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

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

WiseTrack.create(wisetrackConfig);
`

$3

You can use WiseTrack to track all kinds of events. Let's say you want to track every tap on a button. Simply create a new event token in your [dashboard]. Let's say that event token is abc123. You can add the following line in your button’s click handler method to track the click:

`js
var wisetrackEvent = new WiseTrackEvent("abc123");
WiseTrack.trackEvent(wisetrackEvent);
`

$3

If your users can generate revenue by tapping on advertisements or making In-App Purchases, then you can track those revenues with events. Let's say a tap is worth €0.01. You could track the revenue event like this:

`js
var wisetrackEvent = new WiseTrackEvent("abc123");

wisetrackEvent.setRevenue(0.01, "EUR");

WiseTrack.trackEvent(wisetrackEvent);
`

When you set a currency token, WiseTrack will automatically convert the incoming revenues into a reporting revenue of your choice. Read more about [currency conversion here][currency-conversion].

$3

You can also add an optional transaction ID to avoid tracking duplicate revenues. The last ten transaction IDs are remembered, and revenue events with duplicate transaction IDs are skipped. This is especially useful for In-App Purchase tracking. You can see an example below.

If you want to track in-app purchases, please make sure to call the trackEvent only if the transaction is finished and an item is purchased. That way you can avoid tracking revenue that is not actually being generated.

`js
var wisetrackEvent = new WiseTrackEvent("abc123");

wisetrackEvent.setRevenue(0.01, "EUR");
wisetrackEvent.setTransactionId("{YourTransactionId}");

WiseTrack.trackEvent(wisetrackEvent);
`

Note: Transaction ID is the iOS term, unique identifier for successfully finished Android In-App-Purchases is named Order ID.

$3

You can also register a callback URL for that event in your [dashboard][dashboard] and we will send a GET request to that URL whenever the event gets tracked. In that case you can also put some key-value pairs in an object and pass it to the trackEvent method. We will then append these named parameters to your callback URL.

For example, suppose you have registered the URL http://www.wisetrack.com/callback for your event with event token abc123 and execute the following lines:

`js
var wisetrackEvent = new WiseTrackEvent("abc123");

wisetrackEvent.addCallbackParameter("key", "value");
wisetrackEvent.addCallbackParameter("foo", "bar");

WiseTrack.trackEvent(wisetrackEvent);
`

In that case we would track the event and send a request to:

`
http://www.wisetrack.com/callback?key=value&foo=bar
`

It should be mentioned that we support a variety of placeholders like {idfa} for iOS or {gps_adid} for Android that can be used as parameter values. In the resulting callback the {idfa} placeholder would be replaced with the ID for Advertisers of the current device for iOS and the {gps_adid} would be replaced with the Google Advertising ID of the current device for Android. Also note that we don't store any of your custom parameters, but only append them to your callbacks. If you haven't registered a callback for an event, these parameters won't even be read.

You can read more about using URL callbacks, including a full list of available values, in our
[callbacks guide][callbacks-guide].

Note: Both parameters in this method must be strings. If either of the passed parameters is not a string, the key-value pair will not be added to the parameters list.

$3

Similarly to the callback parameters mentioned above, you can also add parameters that WiseTrack will transmit to the network partners of your choice. You can activate these networks in your WiseTrack dashboard.

This works similarly to the callback parameters mentioned above, but can be added by calling the addPartnerParameter method on your WiseTrackEvent instance.

`js
var wisetrackEvent = new WiseTrackEvent("abc123");

wisetrackEvent.addPartnerParameter("key", "value");
wisetrackEvent.addPartnerParameter("foo", "bar");

WiseTrack.trackEvent(wisetrackEvent);
`

You can read more about special partners and networks in our [guide to special partners][special-partners].

Note: Both parameters in this method must be strings. If either of the passed parameters is not a string, the key-value pair will not be added to the parameters list.

$3

You can also add custom string identifier to each event you want to track. This identifier will later be reported in event success and/or event failure callbacks to enable you to keep track on which event was successfully tracked or not. You can set this identifier by calling the setCallbackId method on your WiseTrackEvent instance:

`js
var wisetrackEvent = new WiseTrackEvent("abc123");

wisetrackEvent.setCallbackId("Your-Custom-Id");

WiseTrack.trackEvent(wisetrackEvent);
`

$3

Note: This feature is only available in the SDK v4.22.0 and above.

You can track App Store and Play Store subscriptions and verify their validity with the WiseTrack SDK. After a subscription has been successfully purchased, make the following call to the WiseTrack SDK:

For App Store subscription:

`js
var subscription = new WiseTrackAppStoreSubscription(price, currency, transactionId, receipt);
subscription.setTransactionDate(transactionDate);
subscription.setSalesRegion(salesRegion);

WiseTrack.trackAppStoreSubscription(subscription);
`

For Play Store subscription:

`js
var subscription = new WiseTrackPlayStoreSubscription(price, currency, sku, orderId, signature, purchaseToken);
subscription.setPurchaseTime(purchaseTime);

WiseTrack.trackPlayStoreSubscription(subscription);
`

Subscription tracking parameters for App Store subscription:

- price
- currency (you need to pass currencyCode of the priceLocale object)
- transactionId
- receipt
- transactionDate
- salesRegion (you need to pass countryCode of the priceLocale object)

Subscription tracking parameters for Play Store subscription:

- price
- currency
- sku
- orderId
- signature
- purchaseToken
- purchaseTime

Note: Subscription tracking API offered by WiseTrack SDK expects all parameters to be passed as string values. Parameters described above are the ones which API exects you to pass to subscription object prior to tracking subscription. There are various libraries which are handling in app purchases in React Native and each one of them should return information described above in some form upon successfully completed subscription purchase. You should locate where these parameters are placed in response you are getting from library you are using for in app purchases, extract those values and pass them to WiseTrack API as string values.

Just like with event tracking, you can attach callback and partner parameters to the subscription object as well:

For App Store subscription:

`js
var subscription = new WiseTrackAppStoreSubscription(price, currency, transactionId, receipt);
subscription.setTransactionDate(transactionDate);
subscription.setSalesRegion(salesRegion);

// add callback parameters
subscription.addCallbackParameter("key", "value");
subscription.addCallbackParameter("foo", "bar");

// add partner parameters
subscription.addPartnerParameter("key", "value");
subscription.addPartnerParameter("foo", "bar");

WiseTrack.trackAppStoreSubscription(subscription);
`

For Play Store subscription:

`js
var subscription = new WiseTrackPlayStoreSubscription(price, currency, sku, orderId, signature, purchaseToken);
subscription.setPurchaseTime(purchaseTime);

// add callback parameters
subscription.addCallbackParameter("key", "value");
subscription.addCallbackParameter("foo", "bar");

// add partner parameters
subscription.addPartnerParameter("key", "value");
subscription.addPartnerParameter("foo", "bar");

WiseTrack.trackPlayStoreSubscription(subscription);
`

$3

Some parameters are saved to be sent in every event and session of the WiseTrack SDK. Once you have added any of these parameters, you don't need to add them every time, since they will be saved locally. If you add the same parameter twice, there will be no effect.

These session parameters can be called before the WiseTrack SDK is launched to make sure they are sent even on install. If you need to send them with an install, but can only obtain the needed values after launch, it's possible to delay the first launch of the WiseTrack SDK to allow this behaviour.

$3

The same callback parameters that are registered for events can be also saved to be sent in every event or session of the WiseTrack SDK.

The session callback parameters have a similar interface of the event callback parameters. Instead of adding the key and its value to an event, it's added through a call to method addSessionCallbackParameter of the WiseTrack instance:

`js
WiseTrack.addSessionCallbackParameter("foo", "bar");
`

The session callback parameters will be merged with the callback parameters and added to an event. The callback parameters added to an event have precedence over the session callback parameters. Meaning that, when adding a callback parameter to an event with the same key to one added from the session, the value that prevails is the callback parameter added to the event.

Note: Both parameters in this method must be strings. If either of the passed parameters is not a string, the key-value pair will not be added to the parameters list.

It's possible to remove a specific session callback parameter by passing the desiring key to the method removeSessionCallbackParameter of the WiseTrack instance:

`js
WiseTrack.removeSessionCallbackParameter("foo");
`

If you wish to remove all key and values from the session callback parameters, you can reset it with the method resetSessionCallbackParameters of the WiseTrack instance:

`js
WiseTrack.resetSessionCallbackParameters();
`

$3

In the same way that there are session callback parameters that are sent for every event or session of the WiseTrack SDK, there are also session partner parameters.

These will be transmitted to network partners, for the integrations that have been activated in your WiseTrack [dashboard].

The session partner parameters have a similar interface to the event partner parameters. Instead of adding the key and its value to an event, it's added through a call to method addSessionPartnerParameter of the WiseTrack instance:

`js
WiseTrack.addSessionPartnerParameter("foo", "bar");
`

The session partner parameters will be merged with the partner parameters and added to an event. The partner parameters added to an event have precedence over the session partner parameters. Meaning that, when adding a partner parameter to an event with the same key to one added from the session, the value that prevails is the partner parameter added to the event.

Note: Both parameters in this method must be strings. If either of the passed parameters is not a string, the key-value pair will not be added to the parameters list.

It's possible to remove a specific session partner parameter by passing the desiring key to the method removeSessionPartnerParameter of the WiseTrack instance:

`js
WiseTrack.removeSessionPartnerParameter("foo");
`

If you wish to remove all keys and values from the session partner parameters, you can reset it with the method resetSessionPartnerParameters of the WiseTrack instance:

`js
WiseTrack.resetSessionPartnerParameters();
`

$3

Delaying the start of the WiseTrack SDK allows your app some time to obtain session parameters, such as unique identifiers, to be sent on install.

Set the initial delay time in seconds with the setDelayStart field of the WiseTrackConfig instance:

`js
wisetrackConfig.setDelayStart(5.5);
`

In this case this will make the WiseTrack SDK not send the initial install session and any event created for 5.5 seconds. After this time is expired or if you call sendFirstPackages() of the WiseTrack instance in the meanwhile, every session parameter will be added to the delayed install session and events and the WiseTrack SDK will resume as usual.

The maximum delay start time of the WiseTrack SDK is 10 seconds.

$3

You can register a listener to be notified of tracker attribution changes. Due to the different sources considered for attribution, this information cannot be provided synchronously. The simplest way is to create a single anonymous listener which is going to be called each time your user's attribution value changes:

With the WiseTrackConfig instance, before starting the SDK, add the anonymous listener:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setAttributionCallbackListener(function(attribution) {
// Printing all attribution properties.
console.log("Attribution changed!");
console.log(attribution.trackerToken);
console.log(attribution.trackerName);
console.log(attribution.network);
console.log(attribution.campaign);
console.log(attribution.adgroup);
console.log(attribution.creative);
console.log(attribution.clickLabel);
console.log(attribution.adid);
console.log(attribution.costType);
console.log(attribution.costAmount);
console.log(attribution.costCurrency);
console.log(attribution.fbInstallReferrer);
});

WiseTrack.create(wisetrackConfig);
`

Within the listener function you have access to the attribution parameters. Here is a quick summary of its properties:

- trackerToken the tracker token of the current attribution.
- trackerName the tracker name of the current attribution.
- network the network grouping level of the current attribution.
- campaign the campaign grouping level of the current attribution.
- adgroup the ad group grouping level of the current attribution.
- creative the creative grouping level of the current attribution.
- clickLabel the click label of the current attribution.
- adid the WiseTrack device identifier.
- costType the cost type.
- costAmount the cost amount.
- costCurrency the cost currency.
- fbInstallReferrer the cost currency (Android only).

Please make sure to consider our [applicable attribution data policies][attribution-data].

Note: The cost data - costType, costAmount & costCurrency are only available when configured in WiseTrackConfig by calling setNeedsCost method. If not configured or configured, but not being part of the attribution, these fields will have value null. This feature is available in SDK v4.26.0 and above.

$3

You can register a callback to be notified of successful and failed tracked events and/or sessions.

Follow the same steps as for attribution callback to implement the following callback function for successfully tracked events:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setEventTrackingSucceededCallbackListener(function(eventSuccess) {
// Printing all event success properties.
console.log("Event tracking succeeded!");
console.log(eventSuccess.message);
console.log(eventSuccess.timestamp);
console.log(eventSuccess.eventToken);
console.log(eventSuccess.callbackId);
console.log(eventSuccess.adid);
console.log(eventSuccess.jsonResponse);
});

WiseTrack.create(wisetrackConfig);
`

The following callback function for failed tracked events:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setEventTrackingFailedCallbackListener(function(eventFailure) {
// Printing all event failure properties.
console.log("Event tracking failed!");
console.log(eventFailure.message);
console.log(eventFailure.timestamp);
console.log(eventFailure.eventToken);
console.log(eventFailure.callbackId);
console.log(eventFailure.adid);
console.log(eventFailure.willRetry);
console.log(eventFailure.jsonResponse);
});

WiseTrack.create(wisetrackConfig);
`

For successfully tracked sessions:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setSessionTrackingSucceededCallbackListener(function(sessionSuccess) {
// Printing all session success properties.
console.log("Session tracking succeeded!");
console.log(sessionSuccess.message);
console.log(sessionSuccess.timestamp);
console.log(sessionSuccess.adid);
console.log(sessionSuccess.jsonResponse);
});

WiseTrack.create(wisetrackConfig);
`

And for failed tracked sessions:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setSessionTrackingFailedCallbackListener(function(sessionFailure) {
// Printing all session failure properties.
console.log("Session tracking failed!");
console.log(sessionFailure.message);
console.log(sessionFailure.timestamp);
console.log(sessionFailure.adid);
console.log(sessionFailure.willRetry);
console.log(sessionFailure.jsonResponse);
});

WiseTrack.create(wisetrackConfig);
`

The callback functions will be called after the SDK tries to send a package to the server. Within the callback you have access to a response data object specifically for the callback. Here is a quick summary of the session response data properties:

- var message the message from the server or the error logged by the SDK.
- var timestamp timestamp from the server.
- var adid a unique device identifier provided by WiseTrack.
- var jsonResponse the JSON object with the response from the server.

Both event response data objects contain:

- var eventToken the event token, if the package tracked was an event.
- var callbackId the custom defined callback ID set on event object.

And both event and session failed objects also contain:

- var willRetry indicates there will be an attempt to resend the package at a later time.

$3

You can disable the WiseTrack SDK from tracking by invoking the method setEnabled of the WiseTrack instance with the enabled parameter as false. This setting is remembered between sessions, but it can only be activated after the first session.

`js
WiseTrack.setEnabled(false);
`

You can verify if the WiseTrack SDK is currently active with the method isEnabled of the WiseTrack instance. It is always possible to activate the WiseTrack SDK by invoking setEnabled with the parameter set to true.

$3

You can put the WiseTrack SDK in offline mode to suspend transmission to our servers while retaining tracked data to be sent later. When in offline mode, all information is saved in a file, so be careful not to trigger too many events while in offline mode.

You can activate offline mode by calling the method setOfflineMode of the WiseTrack instance with the parameter true.

`js
WiseTrack.setOfflineMode(true);
`

Conversely, you can deactivate offline mode by calling setOfflineMode with false. When the WiseTrack SDK is put back in online mode, all saved information is send to our servers with the correct time information.

Unlike disabling tracking, this setting is not remembered between sessions. This means that the SDK is in online mode whenever it is started, even if the app was terminated in offline mode.

$3

If your app makes heavy use of event tracking, you might want to delay some HTTP requests in order to send them in one batch every minute. You can enable event buffering with your WiseTrackConfig instance by calling setEventBufferingEnabled method:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setEventBufferingEnabled(true);

WiseTrack.create(wisetrackConfig);
`

$3

In accordance with article 17 of the EU's General Data Protection Regulation (GDPR), you can notify WiseTrack when a user has exercised their right to be forgotten. Calling the following method will instruct the WiseTrack SDK to communicate the user's choice to be forgotten to the WiseTrack backend:

`js
WiseTrack.gdprForgetMe();
`

Upon receiving this information, WiseTrack will erase the user's data and the WiseTrack SDK will stop tracking the user. No requests from this device will be sent to WiseTrack in the future.

Third-party sharing for specific users

You can notify WiseTrack when a user disables, enables, and re-enables data sharing with third-party partners.

$3

Call the following method to instruct the WiseTrack SDK to communicate the user's choice to disable data sharing to the WiseTrack backend:

`js
var wisetrackThirdPartySharing = new WiseTrackThirdPartySharing(false);
WiseTrack.trackThirdPartySharing(wisetrackThirdPartySharing);
`

Upon receiving this information, WiseTrack will block the sharing of that specific user's data to partners and the WiseTrack SDK will continue to work as usual.

$3

Call the following method to instruct the WiseTrack SDK to communicate the user's choice to share data or change data sharing, to the WiseTrack backend:

`js
var wisetrackThirdPartySharing = new WiseTrackThirdPartySharing(true);
WiseTrack.trackThirdPartySharing(wisetrackThirdPartySharing);
`

Upon receiving this information, WiseTrack changes sharing the specific user's data to partners. The WiseTrack SDK will continue to work as expected.

Call the following method to instruct the WiseTrack SDK to send the granular options to the WiseTrack backend:

`js
var wisetrackThirdPartySharing = new WiseTrackThirdPartySharing(null);
wisetrackThirdPartySharing.addGranularOption("PartnerA", "foo", "bar");
WiseTrack.trackThirdPartySharing(wisetrackThirdPartySharing);
`

$3

You can notify WiseTrack when a user exercises their right to change data sharing with partners for marketing purposes, but they allow data sharing for statistical purposes.

Call the following method to instruct the WiseTrack SDK to communicate the user's choice to change data sharing, to the WiseTrack backend:

`js
WiseTrack.trackMeasurementConsent(true);
`

Upon receiving this information, WiseTrack changes sharing the specific user's data to partners. The WiseTrack SDK will continue to work as expected.

$3

When you set up the SDK Signature, each SDK communication package is "signed". This lets WiseTrack’s servers easily detect and reject any install activity that is not legitimate.

There are just a few steps involved in setting up the SDK Signature. Please contact your Technical Account Manager or support@wisetrack.com to get started.

$3

The default behaviour of the WiseTrack SDK is to pause sending HTTP requests while the app is in the background. You can change this in your WiseTrackConfig instance by calling setSendInBackground method:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setSendInBackground(true);

WiseTrack.create(wisetrackConfig);
`

If nothing is set, sending in background is disabled by default.

$3

Certain services (such as Google Analytics) require you to coordinate device and client IDs in order to prevent duplicate reporting.

$3

You can access the IDFA value of an iOS device by invoking the getIdfa method of the WiseTrack instance and passing it a callback that will get triggered once the IDFA value has been obtained by the native iOS SDK:

`javascript
WiseTrack.getIdfa((idfa) => {
console.log("IDFA = " + idfa);
});
`

$3

The Google Play Services Advertising Identifier (Google advertising ID) is a unique identifier for a device. Users can opt out of sharing their Google advertising ID by toggling the "Opt out of Ads Personalization" setting on their device. When a user has enabled this setting, the WiseTrack SDK returns a string of zeros when trying to read the Google advertising ID.

> Important: If you are targeting Android 12 and above (API level 31), you need to add the com.google.android.gms.AD_ID permission to your app. If you do not add this permission, you will not be able to read the Google advertising ID even if the user has not opted out of sharing their ID.

The WiseTrack SDK allows you to read the Google advertising identifier of the Android device on which your app is running. In order to do this, call the getGoogleAdId method of the WiseTrack instance and pass your callback as a parameter. Once obtained by the native Android SDK, you will receive the Google advertising identifier value in your callback method:

`javascript
WiseTrack.getGoogleAdId((googleAdId) => {
console.log("Google Ad Id = " + googleAdId);
});
`

$3

If you need to obtain the Amazon advertising ID, you can call the getAmazonAdId method of the WiseTrack instance and pass your callback as a parameter to which the Amazon advertising ID value will be sent once obtained:

`javascript
WiseTrack.getAmazonAdId((amazonAdId) => {
console.log("Amazon Ad Id = " + amazonAdId);
});
`

$3

For every device with your app installed on it, the WiseTrack backend generates a unique WiseTrack device identifier (adid). In order to obtain this identifier, call the getAdid method of the WiseTrack instance and pass your callback as a parameter to which the adid value will be sent once obtained:

`javascript
WiseTrack.getAdid((adid) => {
console.log("Adid = " + adid);
});
`

Note: Information about the adid is only available after an app installation has been tracked by the WiseTrack backend. From that moment on, the WiseTrack SDK has information about the device adid and you can access it with this method. So, it is not possible to access the adid value before the SDK has been initialized and installation of your app has been successfully tracked.

$3

> Note If you want to use external device IDs, please contact your WiseTrack representative. They will talk you through the best approach for your use case.

An external device identifier is a custom value that you can assign to a device or user. They can help you to recognize users across sessions and platforms. They can also help you to deduplicate installs by user so that a user isn't counted as multiple new installs.

You can also use an external device ID as a custom identifier for a device. This can be useful if you use these identifiers elsewhere and want to keep continuity.

Check out our external device identifiers article for more information.

> Note This setting requires WiseTrack SDK v4.21.0 or later.

To set an external device ID, assign the identifier to the externalDeviceId property of your config instance. Do this before you initialize the WiseTrack SDK.

`js
wisetrackConfig.setExternalDeviceId("{Your-External-Device-Id}");
`

> Important: You need to make sure this ID is unique to the user or device depending on your use-case. Using the same ID across different users or devices could lead to duplicated data. Talk to your WiseTrack representative for more information.

If you want to use the external device ID in your business analytics, you can pass it as a session callback parameter. See the section on session callback parameters for more information.

You can import existing external device IDs into WiseTrack. This ensures that the backend matches future data to your existing device records. If you want to do this, please contact your WiseTrack representative.

$3

This callback is triggered as described in the attribution callback section, providing you with information about a new attribution whenever it changes. If you want to access information about a user's current attribution status at any other time, you can make a call to the getAttribution method of the WiseTrack instance and pass your callback as a parameter to which the attribution value will be sent once obtained:

`javascript
WiseTrack.getAttribution((attribution) => {
console.log("Tracker token = " + attribution.trackerToken);
console.log("Tracker name = " + attribution.trackerName);
console.log("Network = " + attribution.network);
console.log("Campaign = " + attribution.campaign);
console.log("Adgroup = " + attribution.adgroup);
console.log("Creative = " + attribution.creative);
console.log("Click label = " + attribution.clickLabel);
console.log("Adid = " + attribution.adid);
});
`

Note: Information about a user's current attribution status is only available after an app installation has been tracked by the WiseTrack backend and the attribution callback has been triggered. From that moment on, the WiseTrack SDK has information about a user's attribution status and you can access it with this method. So, it is not possible to access a user's attribution value before the SDK has been initialized and an attribution callback has been triggered.

$3

To send us the push notification token, add the following call to WiseTrack whenever you get your token in the app or when it gets updated:

`js
WiseTrack.setPushToken("YourPushNotificationToken");
`

Push tokens are used for Audience Builder and client callbacks, and they are required for the upcoming uninstall tracking feature.

$3

If you are distributing your Android app outside of the Google Play Store and would like to track additional device identifiers (IMEI and MEID), you need to explicitly instruct the WiseTrack SDK to do so. You can do that by calling the setReadMobileEquipmentIdentity method of the WiseTrackConfig instance. The WiseTrack SDK does not collect these identifiers by default.

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setReadMobileEquipmentIdentity(true);

WiseTrack.create(wisetrackConfig);
`

You will also need to add the READ_PHONE_STATE permission to your AndroidManifest.xml file:

`xml

`

In order to use this feature, additional steps are required within your WiseTrack Dashboard. For more information, please contact your dedicated account manager or write an email to support@wisetrack.com.

$3

If you want to use the WiseTrack SDK to recognize users that found your app pre-installed on their device, follow these steps.

1. Create a new tracker in your [dashboard].
2. Open your app delegate and add set the default tracker of your WiseTrackConfig instance:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setDefaultTracker("{TrackerToken}");

WiseTrack.create(wisetrackConfig);
`

Replace {TrackerToken} with the tracker token you created in step 2. Please note that the dashboard displays a tracker
URL (including http://app.wisetrack.com/). In your source code, you should specify only the six-character token and not the
entire URL.

3. Build and run your app. You should see a line like the following in the app's log output:

`
Default tracker: 'abc123'
`

$3

If you are using the WiseTrack tracker URL with an option to deep link into your app from the URL, there is the possibility to get info about the deep link URL and its content. Hitting the URL can happen when the user has your app already installed (standard deep linking scenario) or if they don't have the app on their device (deferred deep linking scenario).

$3

To support deep linking in Android, the app's AndroidManifest.xml file will need to be modified. Please refer to this [page of our Android SDK][android-sdk-deeplink] for the needed modifications to AndroidManifest.xml.

To support deep linking in iOS 8 or earlier, the app's Info.plist file will need to be modified. Please refer to this [page of our iOS SDK][ios-sdk-deeplink-early] for the needed modifications to Info.plist.

To support deep linking in iOS 9 or later, your app would have to handle Universal Links. Please refer to this [page of our iOS SDK][ios-sdk-deeplink-late] for the needed modifications.

After that, refer to this page of the [React Native offical docs][rn-linking] for instructions on how to support both platforms and obtain deep link URL in your JavaScript code.

$3

While deferred deep linking is not supported out of the box on Android and iOS, our WiseTrack SDK makes it possible.

In order to get info about the URL content in a deferred deep linking scenario, you should set a callback method on the WiseTrackConfig object which will receive one parameter where the content of the URL will be delivered. You should set this method on the config object by calling the method setDeferredDeeplinkCallbackListener:

`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setDeferredDeeplinkCallbackListener(function(deeplink) {
console.log("Deferred deep link URL content: " + deeplink);
});

WiseTrack.create(wisetrackConfig);
`

In the deferred deep linking scenario, there is one additional setting which can be set on the WiseTrackConfig object. Once the WiseTrack SDK gets the deferred deep link info, we are offering you the possibility to choose whether our SDK should open this URL or not. You can choose to set this option by calling the setShouldLaunchDeeplink method on the config object:


`js
var wisetrackConfig = new WiseTrackConfig(appToken, environment);

wisetrackConfig.setShouldLaunchDeeplink(true);
// or wisetrackConfig.setShouldLaunchDeeplink(false);

wisetrackConfig.setDeferredDeeplinkCallbackListener(function(deeplink) {
console.log("Deferred deep link URL content: " + deeplink);
});

WiseTrack.create(wisetrackConfig);
`

If nothing is set, the WiseTrack SDK will always try to launch the URL by default.

$3

WiseTrack enables you to run re-engagement campaigns by using deep links. For more information on this, please check our [official docs][reattribution-with-deeplinks].

If you are using this feature, in order for your user to be properly reattributed, you need to make one additional call to the WiseTrack SDK in your app. Once you have received deep link content information in your app, add a call to appWillOpenUrl method of the WiseTrack instance. By making this call, the WiseTrack SDK will try to find if there is any new attribution info inside of the deep link and if any, it will be sent to the WiseTrack backend. If your user should be reattributed due to a click on the WiseTrack tracker URL with deep link content in it, you will see the attribution callback in your app being triggered with new attribution info for this user.

Call to the appWillOpenUrl method in a React component would look like this:

`js
componentDidMount() {
Linking.addEventListener('url', this.handleDeepLink);
Linking.getInitialURL().then((url) => {
if (url) {
this.handleDeepLink({ url });
}
})
}

componentWillUnmount() {
Linking.removeEventListener('url', this.handleDeepLink);
}

handleDeepLink(event) {
WiseTrack.appWillOpenUrl(event.url);
}
`

$3

In order to enable data residency feature, make sure to call setUrlStrategy method of the WiseTrackConfig instance with one of the following constants:

`js
wisetrackConfig.setUrlStrategy(WiseTrackConfig.DataResidencyEU); // for EU data residency region
wisetrackConfig.setUrlStrategy(WiseTrackConfig.DataResidencyTR); // for Turkey data residency region
wisetrackConfig.setUrlStrategy(WiseTrackConfig.DataResidencyUS); // for US data residency region
`

$3

By default WiseTrack SDK doesn't mark app as COPPA compliant. In order to mark your app as COPPA compliant, make sure to call setCoppaCompliantEnabled method of WiseTrackConfig instance with parameter true:

`js
wisetrackConfig.setCoppaCompliantEnabled(true);
`

Note: By enabling this feature, third-party sharing will be automatically disabled for the users. If later during the app lifetime you decide not to mark app as COPPA compliant anymore, third-party sharing will not be automatically re-enabled. Instead, next to not marking your app as COPPA compliant anymore, you will need to explicitly re-enable third-party sharing in case you want to do that.

$3

Note: This feature exists only in Android platform.

By default WiseTrack SDK doesn't mark Android app as Play Store Kids App. In order to mark your app as the app which is targetting kids in Play Store, make sure to call setPlayStoreKidsAppEnabled method of WiseTrackConfig instance with parameter true:

`js
wisetrackConfig.setPlayStoreKidsAppEnabled(true);
``

[dashboard]: http://wisetrack.com
[wisetrack.com]: http://wisetrack.com

[example]: ./example
[npm-repo]: https://www.npmjs.com/package/react-native-wisetrack

[rn-linking]: https://facebook.github.io/react-native/docs/linking.html
[google-ad-id]: https://support.google.com/googleplay/android-developer/answer/6048248?hl=en
[enable-ulinks]: https://github.com/wisetrack/ios_sdk#deeplinking-setup-new
[event-tracking]: https://docs.wisetrack.com/en/event-tracking
[callbacks-guide]: https://docs.wisetrack.com/en/callbacks
[attribution-data]: https://github.com/wisetrack/sdks/blob/master/doc/attribution-data.md
[special-partners]: https://docs.wisetrack.com/en/special-partners
[broadcast-receiver]: https://github.com/wisetrack/android_sdk#gps-intent

[google-launch-modes]: http://developer.android.com/guide/topics/manifest/activity-element.html#lmode
[currency-conversion]: https://docs.wisetrack.com/en/event-tracking/#tracking-purchases-in-different-currencies
[google-play-services]: http://developer.android.com/google/play-services/index.html
[android-sdk-deeplink]: https://github.com/wisetrack/android_sdk#deeplinking-standard
[google-play-services]: http://developer.android.com/google/play-services/setup.html
[ios-sdk-deeplink-late]: https://github.com/wisetrack/ios_sdk#-deep-linking-on-ios-9-and-later
[ios-sdk-deeplink-early]: https://github.com/wisetrack/ios_sdk#-deep-linking-on-ios-8-and-earlier
[broadcast-receiver-custom]: https://github.com/wisetrack/android_sdk/blob/master/doc/english/referrer.md

[reattribution-with-deeplinks]: https://docs.wisetrack.com/en/deeplinking/#manually-appending-attribution-data-to-a-deep-link

License

The WiseTrack SDK is licensed under the MIT License.

Copyright (c) 2012-Present WiseTrack GmbH, http://www.wisetrack.com

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.