Skip to main content

Basic Setup

Example apps​

You can check how our SDK can be used in the web app by checking example apps or demo app in this repository.

Integrate​

Add Adtrace to project​

This SDK can be used to track installs, sessions and events. Simply add the Adtrace Web SDK to your web app.

Our SDK is exposed under all module definitions, so it works under CommonJS and AMD environments and is also available through global Adtrace when imported through script tag in HTML.

To load the Adtrace Web SDK paste the following snippet into the <head> tag:

<script type="application/javascript" src="./dist/adtrace-latest.min.js"></script>

The Adtrace Web SDK should be loaded only once per page, and it should be initiated once per page load.

It's also possible to install our sdk through NPM:

npm install web-adtrace --save

and import

import Adtrace from "web-adtrace"

Initialization​

In order to initialize the Adtrace Web SDK you must call the Adtrace.initSdk method as soon as possible:

Adtrace.initSdk({
  appToken: 'YOUR_APP_TOKEN',
  environment: 'production'
});

Mandatory params​

appToken string​

Initialization method requires this parameter, so make sure to provide valid app token

environment string​

This param is also mandatory. Available options are production or sandbox. Use sandbox in case you are testing the SDK locally with your web app

Optional params​

attributionCallback function​

This param accepts function, and it's a callback function for the attribution change. Two arguments are provided to the callback, first one is an internal event name (can be ignored), and the other one is the object which holds information about the changed attribution

Example:

Adtrace.initSdk({
  // ... other params go here, including mandatory ones
  attributionCallback: function (e, attribution) {
    // e: internal event name, can be ignored
    // attribution: details about the changed attribution
  }
});

defaultTracker string​

By default, users who are not attributed to any campaigns will be attributed to the Organic tracker of the app. If you want to overwrite this behaviour and attributed this type of traffic under a different tracker, you can use this method to set a different default tracker.

customUrl string​

By default, all requests go to adtrace's endpoints. You are able to redirect all requests to your custom endpoint

eventDeduplicationListLimit number​

By default, this param is set to 10. It is possible to override this limit but make sure that it is a positive number and not too big. This will cache last n deduplication ids (defined by this param) and use them to deduplicate events with repeating ids

logLevel string​

By default, this param is set to error. Possible values are none, error, warning, info, verbose. We highly recommend that you use verbose when testing in order to see precise logs and to make sure integration is done properly. Here are more details about each log level:

  • verbose - will print detailed messages in case of certain actions
  • info - will print only basic info messages, warnings and errors
  • warning - will print only warning and error messages
  • error - will print only error message
  • none - won't print anything

logOutput string​

It's possible to define html container where you want to see your logs. This is useful when testing on mobile devices and when you want to see logs directly on the screen (recommended only for testing)

namespace string​

A custom namespace for SDK data storage. If there are multiple applications on the same domain to allow SDK distinguish storages and don't mix the data up each application should use its own namespace.

Attention

Please note it's possible to set custom namespace for existing storage with default name, all data will be preserved and moved to the custom namespace. Once custom namespace is set it's not possible to rename it without data loss.

externalDeviceId string (ONLY SDK)​

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.

Adtrace.initSdk({
  // other initialisation options go here
  externalDeviceId: 'YOUR_EXTERNAL_DEVICE_ID', // optional
});
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 callback parameter. See the section on global callback parameters for more information.