Additional Features

Attribution callback

You can register a callback to be notified of tracker attribution changes. Due to the different sources considered for attribution, this information can not be provided synchronously.

With the config instance, before starting the SDK, add the attribution callback:

AdTraceConfig adtraceConfig = new AdTraceConfig(yourAppToken, environment);
config.attributionCallback = (AdTraceAttribution attributionChangedData) {
    print('[AdTrace]: Attribution changed!');

    if (attributionChangedData.trackerToken != null) {
      print('[AdTrace]: Tracker token: ' + attributionChangedData.trackerToken!);
    }
    if (attributionChangedData.trackerName != null) {
      print('[AdTrace]: Tracker name: ' + attributionChangedData.trackerName!);
    }
    if (attributionChangedData.campaign != null) {
      print('[AdTrace]: Campaign: ' + attributionChangedData.campaign!);
    }
    if (attributionChangedData.network != null) {
      print('[AdTrace]: Network: ' + attributionChangedData.network!);
    }
    if (attributionChangedData.creative != null) {
      print('[AdTrace]: Creative: ' + attributionChangedData.creative!);
    }
    if (attributionChangedData.adgroup != null) {
      print('[AdTrace]: Adgroup: ' + attributionChangedData.adgroup!);
    }
    if (attributionChangedData.clickLabel != null) {
      print('[AdTrace]: Click label: ' + attributionChangedData.clickLabel!);
    }
    if (attributionChangedData.adid != null) {
      print('[AdTrace]: Adid: ' + attributionChangedData.adid!);
    }
    if (attributionChangedData.costType != null) {
      print('[AdTrace]: Cost type: ' + attributionChangedData.costType!);
    }
    if (attributionChangedData.costAmount != null) {
      print('[AdTrace]: Cost amount: ' +
          attributionChangedData.costAmount!.toString());
    }
    if (attributionChangedData.costCurrency != null) {
      print('[AdTrace]: Cost currency: ' +
          attributionChangedData.costCurrency!);
    }
};
AdTrace.start(adtraceConfig);

The callback function will be called after the SDK receives the final attribution data. Within the callback function you have access to the attribution parameter. Here is a quick summary of its properties:

trackerToken the tracker token string of the current attribution.
trackerName the tracker name string of the current attribution.
network the network grouping level string of the current attribution.
campaign the campaign grouping level string of the current attribution.
adgroup the ad group grouping level string of the current attribution.
creative the creative grouping level string of the current attribution.
clickLabel the click label string of the current attribution.
adid the Adtrace device identifier string.
costType the cost type string
costAmount the cost amount
costCurrency the cost currency string

User attribution

Like described in attribution callback section, this callback get triggered providing you info about new attribution when ever it changes. In case you want to access info about your user's current attribution whenever you need it, you can make a call to following method of the AdTrace instance:

AdTraceAttribution attribution = AdTrace.getAttribution();

note

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

Device IDs

The Adtrace SDK offers you possibility to obtain some of the device identifiers.

IDFA (iOS Identifier)

To obtain the IDFA, call the getIdfa method of the AdTrace instance:

AdTrace.getIdfa().then((idfa) {
  // Use idfa string value.
});

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.

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.

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

To obtain the device Google Advertising identifier, it's necessary to pass a callback function to AdTrace.getGoogleAdId that will receive the Google Advertising ID in its argument, like this:

AdTrace.getGoogleAdId().then((googleAdId) {
  // Use googleAdId string value.
});

AdID (Adtrace device identifier)

For each device with your app installed on it, Adtrace backend generates unique Adtrace device identifier (adid). In order to obtain this identifier, you can make a call the getAdid method of the AdTrace instance:

AdTrace.getAdid().then((adid) {
  // Use adid string value.
});

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

SDK signature

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 calling setAppSecret on your config instance:

AdTraceConfig adtraceConfig = new AdTraceConfig(yourAppToken, environment);
adtraceConfig.setAppSecret(secretId, info1, info2, info3, info4);
AdTrace.start(adtraceConfig);

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 same callback parameters that are registered for events can be also saved to be sent in every event or session of the Adtrace SDK.

The session callback parameters have a similar interface to the event callback parameters. Instead of adding the key, and it's value to an event, it's added through a call to AdTrace.addSessionCallbackParameter(String key, String value):

AdTrace.addSessionCallbackParameter('foo', 'bar');

The session callback parameters will be merged with the callback parameters 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.

It's possible to remove a specific session callback parameter by passing the desiring key to the method AdTrace.removeSessionCallbackParameter(String key).

AdTrace.removeSessionCallbackParameter('foo');

If you wish to remove all keys and their corresponding values from the session callback parameters, you can reset it with the method AdTrace.resetSessionCallbackParameters().

AdTrace.resetSessionCallbackParameters();

Session and event callbacks

You can register a callback to be notified when events or sessions are tracked. There are four callbacks: one for tracking successful events, one for tracking failed events, one for tracking successful sessions and one for tracking failed sessions. You can add any number of callbacks after creating the config object:

AdTraceConfig adtraceConfig = new AdTraceConfig(yourAppToken, environment);

// Set session success tracking delegate.
config.sessionSuccessCallback = (AdTraceSessionSuccess sessionSuccessData) {
    print('[AdTrace]: Session tracking success!');

    if (sessionSuccessData.message != null) {
      print('[AdTrace]: Message: ' + sessionSuccessData.message!);
    }
    if (sessionSuccessData.timestamp != null) {
      print('[AdTrace]: Timestamp: ' + sessionSuccessData.timestamp!);
    }
    if (sessionSuccessData.adid != null) {
      print('[AdTrace]: Adid: ' + sessionSuccessData.adid!);
    }
    if (sessionSuccessData.jsonResponse != null) {
      print('[AdTrace]: JSON response: ' + sessionSuccessData.jsonResponse!);
    }
};

// Set session failure tracking delegate.
config.sessionFailureCallback = (AdTraceSessionFailure sessionFailureData) {
    print('[AdTrace]: Session tracking failure!');

    if (sessionFailureData.message != null) {
      print('[AdTrace]: Message: ' + sessionFailureData.message!);
    }
    if (sessionFailureData.timestamp != null) {
      print('[AdTrace]: Timestamp: ' + sessionFailureData.timestamp!);
    }
    if (sessionFailureData.adid != null) {
      print('[AdTrace]: Adid: ' + sessionFailureData.adid!);
    }
    if (sessionFailureData.willRetry != null) {
      print('[AdTrace]: Will retry: ' + sessionFailureData.willRetry.toString());
    }
    if (sessionFailureData.jsonResponse != null) {
      print('[AdTrace]: JSON response: ' + sessionFailureData.jsonResponse!);
    }
};

// Set event success tracking delegate.
config.eventSuccessCallback = (AdTraceEventSuccess eventSuccessData) {
    print('[AdTrace]: Event tracking success!');

    if (eventSuccessData.eventToken != null) {
      print('[AdTrace]: Event token: ' + eventSuccessData.eventToken!);
    }
    if (eventSuccessData.message != null) {
      print('[AdTrace]: Message: ' + eventSuccessData.message!);
    }
    if (eventSuccessData.timestamp != null) {
      print('[AdTrace]: Timestamp: ' + eventSuccessData.timestamp!);
    }
    if (eventSuccessData.adid != null) {
      print('[AdTrace]: Adid: ' + eventSuccessData.adid!);
    }
    if (eventSuccessData.callbackId != null) {
      print('[AdTrace]: Callback ID: ' + eventSuccessData.callbackId!);
    }
    if (eventSuccessData.jsonResponse != null) {
      print('[AdTrace]: JSON response: ' + eventSuccessData.jsonResponse!);
    }
};

// Set event failure tracking delegate.
config.eventFailureCallback = (AdTraceEventFailure eventFailureData) {
    print('[AdTrace]: Event tracking failure!');

    if (eventFailureData.eventToken != null) {
      print('[AdTrace]: Event token: ' + eventFailureData.eventToken!);
    }
    if (eventFailureData.message != null) {
      print('[AdTrace]: Message: ' + eventFailureData.message!);
    }
    if (eventFailureData.timestamp != null) {
      print('[AdTrace]: Timestamp: ' + eventFailureData.timestamp!);
    }
    if (eventFailureData.adid != null) {
      print('[AdTrace]: Adid: ' + eventFailureData.adid!);
    }
    if (eventFailureData.callbackId != null) {
      print('[AdTrace]: Callback ID: ' + eventFailureData.callbackId!);
    }
    if (eventFailureData.willRetry != null) {
      print('[AdTrace]: Will retry: ' + eventFailureData.willRetry.toString());
    }
    if (eventFailureData.jsonResponse != null) {
      print('[AdTrace]: JSON response: ' + eventFailureData.jsonResponse!);
    }
};

AdTrace.start(adtraceConfig);

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

message message string from the server or the error logged by the SDK.
timestamp timestamp string from the server.
adid a unique string device identifier provided by AdTrace.
jsonResponse the JSON object with the repose from the server.

Both event response data objects contain:

eventToken the event token string, if the package tracked was an event.

And both event and session failed objects also contain:

willRetry boolean which indicates whether 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 delayStart member of the config instance:

adtraceConfig.delayStart = 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 AdTrace.sendFirstPackages() in the meanwhile, every session parameter will be added to the delayed install session and events and the Adtrace SDK will resume as usual.

warning

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

SKAdNetwork framework

note

This feature exists only in iOS platform.

If you have implemented the Adtrace 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 Adtrace 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

note

This feature exists only in iOS platform.

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

AdTrace.updateConversionValue(6);

Set external device ID (Experimental)

danger

This feature is experimental.

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.

note

This setting requires Adtrace SDK v2.0.2 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 Adtrace SDK.

adtraceConfig.externalDeviceId = '{Your-External-Device-Id}';

Remember

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 Adtrace 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 AdTrace. This ensures that the backend matches future data to your existing device records. If you want to do this, please contact your Adtrace representative.

Pre-installed trackers

If you want to use the Adtrace SDK to recognize users whose devices came with your app pre-installed, follow these steps.

Create a new tracker in your panel.
Set the default tracker of your config object:

adtraceConfig.defaultTracker = '{TrackerToken}';

Replace {TrackerToken} with the tracker token you created in step 1. Please note that the panel displays a tracker URL (including https://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 your logs:

Default tracker: 'abc123'

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. While 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 setOfflineMode 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.

Disable tracking

You can disable the Adtrace SDK from tracking any activities of the current device by calling setEnabled with parameter false. This setting is remembered between sessions.

AdTrace.setEnabled(false);

You can check if the Adtrace SDK is currently enabled by calling the function isEnabled. It is always possible to activate the Adtrace SDK by invoking setEnabled with the enabled parameter as true.

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

adtraceConfig.eventBufferingEnabled = true;

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

adtraceConfig.sendInBackground = true;

COPPA compliance

By default, Adtrace SDK doesn't mark app as COPPA compliant. In order to mark your app as COPPA compliant, make sure to call coppaCompliantEnabled method of AdTraceConfig instance with boolean parameter true:

adtraceConfig.coppaCompliantEnabled = 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.

Play Store Kids Apps

By default, Adtrace SDK doesn't mark app as Play Store Kids App. In order to mark your app as the app which is targeting kids in Play Store, make sure to call playStoreKidsAppEnabled method of AdTraceConfig instance with boolean parameter true:

adtraceConfig.playStoreKidsAppEnabled = true;

OAID reading (Huawei devices)

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

Attribution callback​

User attribution​

Device IDs​

IDFA (iOS Identifier)​

GPS ADID (Google Play Services advertising identifier)​

AdID (Adtrace device identifier)​

SDK signature​

Session parameters​

Session callback parameters​

Session and event callbacks​

Delay start​

SKAdNetwork framework​

Update SKAdNetwork conversion value​

Set external device ID (Experimental)​

Pre-installed trackers​

Offline mode​

Disable tracking​

Event buffering​

Background tracking​

COPPA compliance​

Play Store Kids Apps​

OAID reading (Huawei devices)​

Attribution callback

User attribution

Device IDs

IDFA (iOS Identifier)

GPS ADID (Google Play Services advertising identifier)

AdID (Adtrace device identifier)

SDK signature

Session parameters

Session callback parameters

Session and event callbacks

Delay start

SKAdNetwork framework

Update SKAdNetwork conversion value

Set external device ID (Experimental)

Pre-installed trackers

Offline mode

Disable tracking

Event buffering

Background tracking

COPPA compliance

Play Store Kids Apps

OAID reading (Huawei devices)