ammoradi/adtrace_sdk_web

This is the Web SDK of

Summary

This is the guide to the Javascript SDK of AdTrace™ for web apps. You can read more about AdTrace™ at adtrace.io.

Table of contents

• Example apps
• Basic integration
  • Recommendations
  • Basic setup
• Additional features
  • Adtrace Identifier
  • Event tracking
    • Revenue tracking
    • Event value
    • Callback parameters
    • Partner parameters
  • Stable local data
• Use with js libraries
  • React

Example apps

You can check how SDK can be used in the web app by checking example app repository.

Basic integration

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

Or if you are using npm, you can add it to your dependencies like this:

npm install web-adtrace

Recommendations

There are two ways to differentiate users coming from native apps to users coming from web apps if you are not running ad campaigns for your web apps:

• Create new app(s) in your AdTrace dashboard for your web app, pick one of the supported platforms during the creation and use this app token in the AdTrace SDK to initialise it. As with your native apps, organic traffic from your app will then be labelled under the Organic tracker in your AdTrace dashboard.
• Use one of your pre-existing app and hardcode a pre-installed tracker token in the AdTrace SDK. All traffic from your app will then be labelled under the hardcoded tracker in your AdTrace dashboard.

Basic setup

There are a few things to keep in mind while implementing the JS SDK:

• The unique_id is An unuique device identifier such as gps_adid in Android, idfa in iOS or win_adid in Windows. If your app isn't able to access or pass those identifiers, you should pass a similary built UUID.

With this in mind, initialisation of AdTrace JS SDK would look like this inside your web app:

var _adtrace = new AdTrace({
  app_token: 'YourAppToken',
  environment: 'production', // or 'sandbox' in case you are testing SDK locally with your web app
  unique_id: '5056e23a-dc94-123o-b8a2-4ac4e08d45b2' // each web app user needs to have unique identifier,
  default_tracker: 'Your non organic tracker' // optional
});

_adtrace.trackSession(function (result) {
    console.log(result);
  }, function (errorMsg, error) {
    console.log(errorMsg, error);
  }
);

Note: The default_tracker is an optional parameter for attributing data to the non organic trackers.

If it doesn't used, your data will attribiute in organic tracker.

Additional features

Once you integrate the AdTrace JS SDK into your web app, you can take advantage of the following features.

Adtrace Identifier

When initializing of SDK complete, you can get Adtrace Identifier.

var adtraceId = _adtrace.getAdId();

Note: If adtrace id equals null, that means the SDK is installing your data and will take a little time (under 10 seconds).

Event tracking

You can use adtrace to track events. Lets say you want to track every tap on a particular button. You would create a new event token in your dashboard, which has an associated event token - looking something like abc123. In order to track this event from your web app, you should do following:

var _eventConfig = {
  event_token: 'EventToken'
};

_adtrace.trackEvent(_eventConfig, function (result) {
  successCb(result, 'event');
}, function (errorMsg, error) {
  errorCb(errorMsg, error, 'event');
});

Event value

You can also add custom string value to event. You can set this value by adding event_value to your event config:

var _eventConfig = {
  event_token: 'EventToken',
  event_value: 'my-value'
};

_adtrace.trackEvent(_eventConfig, function (result) {
  successCb(result, 'event');
}, function (errorMsg, error) {
  errorCb(errorMsg, error, 'event');
});

Revenue tracking

You can attach revenue to event being tracked with AdTrace JS SDK in case you would like to track some purchase that happened inside your web app. In order to that, you need to attach revenue and currency parameters when tracking event:

var _eventConfig = {
  event_token: 'EventToken',
  revenue: 10,
  currency: 'EUR'
};

_adtrace.trackEvent(_eventConfig, function (result) {
  console.log(result);
}, function (errorMsg, error) {
  console.log(errorMsg, error);
});

When you set a currency token, adtrace will automatically convert the incoming revenues into a reporting revenue of your choice.

Callback parameters

You can register a callback URL for your events in your dashboard. We will send a GET request to that URL whenever the event is tracked. You can add callback parameters to that event by adding callback_params parameter to the map object passed to trackEvent method. We will then append these parameters to your callback URL.

For example, suppose you have registered the URL http://www.mydomain.com/callback then track an event like this:

var _eventConfig = {
  event_token: 'EventToken',
  callback_params: [{
    key: 'key',
    value: 'value'
  }, {
    key: 'foo',
    value: 'bar'
  }],
};

_adtrace.trackEvent(_eventConfig, function (result) {
  console.log(result);
}, function (errorMsg, error) {
  console.log(errorMsg, error);
});

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

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

It should be mentioned that we support a variety of placeholders like {gps_adid} that can be used as parameter values. In the resulting callback this placeholder would be replaced with the ID for Advertisers of the current device. Also note that we don't store any of your custom parameters, but only append them to your callbacks, thus without a callback they will not be saved nor sent to you.

Partner parameters

You can also add parameters to be transmitted to network partners, which have been activated in your AdTrace dashboard.

This works similarly to the callback parameters mentioned above, but can be added by adding partner_params parameter to the map object passed to trackEvent method.

var _eventConfig = {
  event_token: 'EventToken',
  partner_params: [{
    key: 'key',
    value: 'value'
  }, {
    key: 'foo',
    value: 'bar'
  }],
};

_adtrace.trackEvent(_eventConfig, function (result) {
  console.log(result);
}, function (errorMsg, error) {
  console.log(errorMsg, error);
});

Stable local data

Because the unique device identifer & adtrace identifer saved in localStorage. If you want to clear the localStorage consider that to call stableLocalData after clear method to save those identifiers in localStorage:

localStorage.clear(); // clearing your own data
_adtrace.stableLocalData(); 

Use with js libraries

React

1.install this package using yarn (or npm):

yarn add web-adtrace

2.import web-adtrace anywhere for once (its better to import this lib on one of top level components like App.js):

import 'web-adtrace';

3.create and initialize adtrace instance (you should use window.AdTrace instead of AdTrace):

const adtrace = new window.AdTrace({
  app_token: 'YourAppToken',
  environment: 'production', // or 'sandbox' in case you are testing SDK locally with your web app
  unique_id: '5056e23a-dc94-123o-b8a2-4ac4e08d45b2', // each web app user needs to have unique identifier,
  default_tracker: 'Your non organic tracker' // optional
});

4.use AdTrace's functions like the examples above