Additional Features

Attribution callback

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 AdTraceConfig instance, before starting the SDK, add the anonymous listener:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.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);
});

AdTrace.create(adtraceConfig);

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 Adtrace device identifier.
costType the cost type.
costAmount the cost amount.
costCurrency the cost currency.

User attribution

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 AdTrace instance and pass your callback as a parameter to which the attribution value will be sent once obtained:

AdTrace.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 Adtrace backend and the attribution callback has been triggered. From that moment on, the Adtrace 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.

Session parameters

Some parameters are saved to be sent in every event and session of the Adtrace 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 Adtrace 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 Adtrace SDK to allow this behaviour.

Session callback parameters

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 AdTrace instance:

AdTrace.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.

warning

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 AdTrace instance:

AdTrace.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 AdTrace instance:

AdTrace.resetSessionCallbackParameters();

Session partner parameters

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

These will be transmitted to network partners, for the integrations that have been activated in your Adtrace panel.

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 AdTrace instance:

AdTrace.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.

warning

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 AdTrace instance:

AdTrace.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 AdTrace instance:

AdTrace.resetSessionPartnerParameters();

Session and event callbacks

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:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.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);
});

AdTrace.create(adtraceConfig);

The following callback function for failed tracked events:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.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);
});

AdTrace.create(adtraceConfig);

For successfully tracked sessions:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.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);
});

AdTrace.create(adtraceConfig);

And for failed tracked sessions:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.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);
});

AdTrace.create(adtraceConfig);

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 AdTrace.
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.

Delay start

Delaying the start of the Adtrace 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 AdTraceConfig instance:

adtraceConfig.setDelayStart(5.5);

In this case this will make the Adtrace 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 AdTrace instance in the meanwhile, every session parameter will be added to the delayed install session and events and the Adtrace SDK will resume as usual.

Max delay

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

Disable tracking

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

AdTrace.setEnabled(false);

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

Offline mode

You can put the Adtrace 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 AdTrace instance with the parameter true.

AdTrace.setOfflineMode(true);

Conversely, you can deactivate offline mode by calling setOfflineMode with false. When the Adtrace SDK is put back in online mode, all saved information is sent 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.

Event buffering

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 AdTraceConfig instance by calling setEventBufferingEnabled method:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setEventBufferingEnabled(true);

AdTrace.create(adtraceConfig);

SDK signature

An account manager must activate the Adtrace SDK signature. Contact Adtrace support if you are interested in using this feature.

If the SDK signature has already been enabled on your account, and you have access to App Secrets in your Adtrace panel, please use the method below to integrate the SDK signature into your app.

An App Secret is set by passing all secret parameters (secretId, info1, info2, info3, info4) to setAppSecret method of AdTraceConfig instance:

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setAppSecret(secretId, info1, info2, info3, info4);

AdTrace.create(adtraceConfig);

Background tracking

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

var adtraceConfig = new AdTraceConfig(appToken, environment);

adtraceConfig.setSendInBackground(true);

AdTrace.create(adtraceConfig);

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

Device IDs

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

IDFA (iOS identifier)

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

AdTrace.getIdfa((idfa) => {
    console.log("IDFA = " + idfa);
});

GPS AdId (Google Play Services advertising identifier)

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 Adtrace SDK returns a string of zeros when trying to read the Google advertising ID.

warning

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 Adtrace 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 AdTrace 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:

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

AdId (Adtrace device identifier)

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

AdTrace.getAdid((adid) => {
    console.log("Adid = " + adid);
});

warning

Information about the adid is only available after an app installation has been tracked by the Adtrace backend. From that moment on, the Adtrace 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.

Pre-installed trackers

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

Create a new tracker in your panel.
Open your app delegate and add set the default tracker of your AdTraceConfig instance:

 var adtraceConfig = new AdTraceConfig(appToken, environment);

 adtraceConfig.setDefaultTracker("{TrackerToken}");

 AdTrace.create(adtraceConfig);

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

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

 Default tracker: 'abc123'

OAID reading (Huawei devices)

in order for Adtrace to be able to read OAID on android devices you need to implement plugin for oaid. take a glance at github example of oaid on react native for more information.

Attribution callback​

User attribution​

Session parameters​

Session callback parameters​

Session partner parameters​

Session and event callbacks​

Delay start​

Disable tracking​

Offline mode​

Event buffering​

SDK signature​

Background tracking​

Device IDs​

IDFA (iOS identifier)​

GPS AdId (Google Play Services advertising identifier)​

AdId (Adtrace device identifier)​

Pre-installed trackers​

OAID reading (Huawei devices)​

Attribution callback

User attribution

Session parameters

Session callback parameters

Session partner parameters

Session and event callbacks

Delay start

Disable tracking

Offline mode

Event buffering

SDK signature

Background tracking

Device IDs

IDFA (iOS identifier)

GPS AdId (Google Play Services advertising identifier)

AdId (Adtrace device identifier)

Pre-installed trackers

OAID reading (Huawei devices)