Skip to main content

Getting started with the Web SDK

This guide walks you through the initial setup of the Adtrace Web SDK. You will install the SDK, initialize it on each page load, set attribution data, and verify that installs are recorded.

Example apps: framework examples, demo app.

1. Add the Adtrace SDK​

Add the Adtrace Web SDK to your site or web app using a script tag or NPM.

The SDK works with CommonJS, AMD, and global Adtrace when loaded through a <script> tag.

Script tag (CDN or self-hosted)​

Paste this into your page <head>. Load the SDK once per page:

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

Replace the path with your hosted copy or build output. Check the releases page for the latest version.

NPM​

npm install web-adtrace --save
app.js
import Adtrace from 'web-adtrace';

2. Initialize the SDK​

Call Adtrace.initSdk as early as possible on each page load. The SDK should be initialized once per page load.

Required parameters​

ParameterTypeDescription
appTokenstringYour app token from the Adtrace panel.
environmentstringsandbox for testing, production for live traffic.

Example​

initSdk
Adtrace.initSdk({
  appToken: '{YourAppToken}',
  environment: 'sandbox',
  logLevel: 'verbose',
});

Optional configuration​

Pass additional read-only options in the same object. See Configuration for:

Register an attribution callback in initSdk if you need install or reattribution notifications.

3. Set referrer​

For proper attribution, call setReferrer as close as possible to initialization:

Adtrace.setReferrer('adtrace_external_click_id%3DEXTERNAL_CLICK_ID');

The referrer string must be URL-encoded.

4. Test the integration​

A successful install (first session in a browser profile) must be recorded before sessions and events appear correctly in Adtrace.

Prepare a clean test environment​

To simulate a fresh install:

  1. Clear browser storage completely (localStorage and IndexedDB used by the SDK).
  2. Set environment: 'sandbox' and logLevel: 'verbose' in initSdk.
  3. Load the page and wait for the first session to be sent.

Test with logs​

  1. Open the browser developer console.
  2. After first open, search logs for an adid value in SDK responses.
Console response (example)
"adid": "mhxd6or7d3u57fnbdy2r4urdrdxr7tlr"

Receiving adid means the install was recorded. If you do not see adid, review the setup steps and the example apps.

Test in the Adtrace panel​

  1. Read web_uuid with Adtrace.getWebUUID().
  2. Open Settings → Testing Console in the Adtrace panel.
  3. Enter the web_uuid and check whether an install is recorded.
web_uuid (example)
7c67ef26-830e-49b7-8948-b868b19bf4b3

Test with attribution callback​

If you set attributionCallback in initSdk, the callback should fire after install. When attribution.adid is present, the install was tracked successfully.

See Send callback information.

5. Track events​

After install is verified, track events with Adtrace.trackEvent. See Track events.

Adtrace.trackEvent({
  eventToken: '{YourEventToken}',
});

6. Build for production​

Before you ship:

  1. Set environment to production.
  2. Set logLevel to error or none.
production init
Adtrace.initSdk({
  appToken: '{YourAppToken}',
  environment: 'production',
  logLevel: 'error',
});