English | فارسی

Summary

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

Table of contents

Quick start

• Example apps
• Getting started
  • Add the SDK to your project
• Integrate the SDK into your app
  • Create unique ID
  • Basic setup
  • Track session

Event tracking

• Track event
• Track revenue

Custom parameters

• Custom parameters overview
• Event parameters
  • Event callback parameters
  • Event partner parameters
  • Event value

Additional features

• Adtrace Identifier
• Default tracker
• Stable local data

Use with React libraries

• Next Js

Quick start

Example apps

React example

By using the SDK to your React, you can check React example for better help.

Next example

By using the SDK to your Next JS, you can check Next Js example for better help.

Getting started

These are the minimal steps required to integrate the AdTrace SDK into your web app.

Add the SDK to your project

Simply add the AdTrace React SDK to dependencies by npm or yarn:

npm install react-adtrace

yarn install react-adtrace

Integrate the SDK into your app

To start with, we'll introduce some information about unique_id. Then start basic integration.

Create unique ID

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.

For more information about creating UUID you can check this solution.

Basic setup

• First import AdTrace SDK in above of your code:

  import AdTrace from 'react-adtrace'

• Initialize the SDK inside your App.js:

  const adtrace = new AdTrace({
    app_token: 'YourAppToken',
    environment: 'production', // or 'sandbox' in case you are testing SDK locally with your web app
    unique_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' // each web app user needs to have unique identifier
  });

Replace {YourAppToken} with your app token. You can find this in your AdTrace panel.

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

production
sandbox

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

Track session

After initializing AdTrace SDK, you are feel free to track user session's look like this:

adtrace.trackSession((result) => {
    console.log(result);
  }, (errorMsg, error) => {
    console.log(errorMsg, error);
  }
);

Note: First tracking session take a little bit more time, because AdTrace should attribute and installing user's data first of all;

Event tracking

Track event

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 panel, which has an associated event token - looking something like abc123. In order to track this event from your web app, you should do following:

const eventConfig = {
  event_token: 'EventToken'
};

adtrace.trackEvent(eventConfig, (result) => {
  successCb(result, 'event');
}, (errorMsg, error) => {
  errorCb(errorMsg, error, 'event');
});

Track revenue

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:

const eventConfig = {
  event_token: 'EventToken',
  revenue: 10,
  currency: 'EUR'
};

adtrace.trackEvent(_eventConfig, (result) => {
  console.log(result);
}, (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.

Custom parameters

Custom parameters overview

In addition to the data points that AdTrace SDK collects by default, you can use the AdTrace SDK to track and add to the event as many custom values as you need (user IDs, product IDs, etc.). Custom parameters are only available as raw data (i.e., they won't appear in the AdTrace panel).

You should use callback parameters for the values that you collect for your own internal use, and partner parameters for those that you wish to share with external partners. If a value (e.g. product ID) is tracked both for internal use and to forward it to external partners, the best practice would be to track it both as callback and partner parameters.

Event parameters

Event callback parameters

You can register a callback URL for your events in your panel. 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:

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

adtrace.trackEvent(eventConfig, (result) => {
  console.log(result);
}, (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

Event partner parameters

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

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.

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

adtrace.trackEvent(eventConfig, (result) => {
  console.log(result);
}, (errorMsg, error) => {
  console.log(errorMsg, error);
});

Event value

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

const eventConfig = {
  event_token: 'EventToken',
  event_value: 'my-value'
};

adtrace.trackEvent(eventConfig, (result) => {
  successCb(result, 'event');
}, (errorMsg, error) => {
  errorCb(errorMsg, error, 'event');
});

Additional features

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

Adtrace Identifier

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

const 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).

Default tracker

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

const adtrace = new AdTrace({
  app_token: '{YourAppToken}',
  environment: 'production', // or 'sandbox' in case you are testing SDK locally with your web app
  unique_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', // each web app user needs to have unique identifier
  default_tracker: 'Your non organic tracker' // optional
});

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

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 React libraries

Next Js

• Add the SDK like this.

• Import react-adtrace in componentDidMount method:

  const AdTrace = require('react-adtrace').default;

• Create and initialize adtrace instance :

  this.adtrace = new AdTrace({
    app_token: 'YourAppToken',
    environment: 'production', // or 'sandbox' in case you are testing SDK locally with your web app
    unique_id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' // each web app user needs to have unique identifier
  });

• Your code should look like this:

  	componentDidMount() {
  	  const AdTrace = require('react-adtrace').default;
  	  this.adtrace = new AdTrace({
  	    app_token: '9e8tyd0l38s7',
  	    environment: 'sandbox', // or 'sandbox' in case you are testing SDK locally with your web app
  	    unique_id: '5057e23a-fh94-878o-b8a2-4ac4e20d48b2', // each web app user needs to have unique identifier,
  	  });
  	}

• Use AdTrace's methods like the examples above

Note: Any kind of importing will get an error. You should import react-adtrace look like the tutorial. For more help you can check next-example.