@adjustcom/adjust-web-sdk

This is the guide to the Javascript SDK of Adjust™ for web sites or web apps. You can read more about Adjust™ at [adjust.com].

Usage no npm install needed!

<script type="module">
  import adjustcomAdjustWebSdk from 'https://cdn.skypack.dev/@adjustcom/adjust-web-sdk';
</script>

README

Summary

This is the guide to the Javascript SDK of Adjust™ for web sites or web apps. You can read more about Adjust™ at adjust.com.

Read this in other languages: English, 中文, 日本語, 한국어.

Table of contents

Example apps

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

Installation

This SDK can be used to track installs, sessions and events. Simply add the Adjust 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 Adjust when loaded through CDN.

To lazy load the Adjust Web SDK through CDN paste the following snippet into the <head> tag:

<script type="application/javascript">
!function(t,a,e,r,s,l,d,n,o){t.Adjust=t.Adjust||{},t.Adjust_q=t.Adjust_q||[];for(var c=0;c<l.length;c++)d(t.Adjust,t.Adjust_q,l[c]);n=a.createElement("script"),o=a.getElementsByTagName("script")[0],n.async=!0,n.src="https://cdn.adjust.com/adjust-latest.min.js",n.onload=function(){for(var a=0;a<t.Adjust_q.length;a++)t.Adjust[t.Adjust_q[a][0]].apply(t.Adjust,t.Adjust_q[a][1]);t.Adjust_q=[]},o.parentNode.insertBefore(n,o)}(window,document,0,0,0,["initSdk","trackEvent","addGlobalCallbackParameters","addGlobalPartnerParameters","removeGlobalCallbackParameter","removeGlobalPartnerParameter","clearGlobalCallbackParameters","clearGlobalPartnerParameters","switchToOfflineMode","switchBackToOnlineMode","stop","restart","gdprForgetMe","disableThirdPartySharing"],function(t,a,e){t[e]=function(){a.push([e,arguments])}});
</script>

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

When loading the sdk through CDN we suggest using minified version. You can target specific version like https://cdn.adjust.com/adjust-5.1.1.min.js, or you can target latest version https://cdn.adjust.com/adjust-latest.min.js if you want automatic updates without need to change the target file. The sdk files are cached so they are served as fast as possible, and the cache is refreshed every half an hour. If you want updates immediately make sure to target specific version.

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

npm install @adjustcom/adjust-web-sdk --save

Initialization

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

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

Here is the full list of available parameters for the initSdk method:

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:

Adjust.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 adjust'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)

Event tracking

You can use adjust 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:

Adjust.trackEvent({
  eventToken: 'YOUR_EVENT_TOKEN'
})

Make sure to track event only after you initialize the Adjust SDK. Here is the full list of available parameters for the trackEvent method:

Mandatory params

eventToken string

Track event method requires this parameter, make sure to provide valid event token

Optional params

revenue number

In case you want to attach revenue to an event (for example you would like to track some purchase that happened inside your web app) then you need to provide positive value for this param. It's also mandatory to provide currency param described in the next block

currency string

You need to provide this param if you want to track revenue event. Please use valid currency code like EUR, USD and so on

Example:

Adjust.trackEvent({
  // ... other params go here, including mandatory ones
  revenue: 110,
  currency: 'EUR'
})

When you set a currency token, adjust will automatically convert the incoming revenues into a reporting revenue of your choice. Read more about currency conversion here.

You can read more about revenue and event tracking in the event tracking guide.

callbackParams array

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 callbackParams 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 https://www.mydomain.com/callback then track an event like this:

Adjust.trackEvent({
  // ... other params go here, including mandatory ones
  callbackParams: [
    {key: 'key', value: 'value'}, 
    {key: 'foo', value: 'bar'}
  ]
})

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

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

Please 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.

You can read more about using URL callbacks, including a full list of available values, in our callbacks guide.

partnerParams array

You can also add parameters to be transmitted to network partners, which have been activated in your Adjust dashboard. This works similarly to the callback parameters mentioned above, but can be added by adding partnerParams parameter to the map object passed to trackEvent method:

Adjust.trackEvent({
  // ... other params go here, including mandatory ones
  partnerParams: [
    {key: 'key', value: 'value'}, 
    {key: 'foo', value: 'bar'}
  ]
})

You can read more about special partners and these integrations in our guide to special partners.

deduplicationId string

It's possible to provide event deduplication id in order to avoid tracking duplicated events. Deduplication list limit is set in initialization configuration as described above

Global callback parameters

There are several methods available for global callback parameters like adding, removing and clearing them. Here is the list of each available method:

addGlobalCallbackParameters

It's possible to add global callback parameters, which will be appended automatically to each session and event request. Note that callback params passed directly to trackEvent method will override existing global callback params. This method accepts an array is the same format as for callbackParams parameter from trackEvent method

Example:

Adjust.addGlobalCallbackParameters([
  {key: 'key1', value: 'value1'},
  {key: 'key2', value: 'value2'}
]);

removeGlobalCallbackParameter

To remove particular callback parameter use this method by providing the key of a global callback param which needs to be removed

Example:

Adjust.removeGlobalCallbackParameter('key1');

clearGlobalCallbackParameters

In order to clear all global callback parameters simply call this method

Example:

Adjust.clearGlobalCallbackParameters();

Global partner parameters

It's possible to add, remove and clear global partner parameters in the similar way as for global callback parameters. Here is the list of each available method:

addGlobalPartnerParameters

It's possible to add global partner parameters, which will be appended automatically to each session and event request. Note that partner params passed directly to trackEvent method will override existing global partner params. This method accepts an array is the same format as for partnerParams parameter from trackEvent method

Example:

Adjust.addGlobalPartnerParameters([
  {key: 'key1', value: 'value1'},
  {key: 'key2', value: 'value2'}
]);

removeGlobalPartnerParameter

To remove particular partner parameter use this method by providing the key of a global partner param which needs to be removed

Example:

Adjust.removeGlobalPartnerParameter('key1');

clearGlobalPartnerParameters

In order to clear all global partner parameters simply call this method

Example:

Adjust.clearGlobalPartnerParameters();

Offline/Online mode

By default when initiated Adjust SDK is always in online mode. But you can put it into offline mode if you want to pause all network requests such as tracking events and sessions (although initial session will ignore this mode and will be sent anyway). There are two methods available to swich on and off the offline mode:

switchToOfflineMode

This method will put the Adjust SDK into offline mode

Example:

Adjust.switchToOfflineMode();

switchBackToOnlineMode

This method will put the Adjust SDK back to online mode

Adjust.switchBackToOnlineMode();

Stop/Restart SDK

It's possible to completely stop the SDK from running in certain situations. This means that SDK will stop tracking sessions and events and in general will stop working entirely. But it's possible to restart it after some time. Here are available methods for this functionality:

stop

This will stop running Adjust SDK

Example:

Adjust.stop();

restart

This will restart Adjust SDK

Example:

Adjust.restart();

GDPR Forget Me

There is functionality available to GDPR Forget particular user. This will notify our backend behind the scene and will stop Adjust SDK from running. There is one method available for this:

gdprForgetMe

This method will stop Adjust SDK from running and will notify adjust backend that user wants to be GDPR forgotten. Once this method is run it's not possible to restart Adjust SDK anymore.

Example:

Adjust.gdprForgetMe();

You can find more details here

Marketing Opt-out

There is functionality for the Marketing Opt-out, which is disabling third-party sharing ability. This will notify our backed in the same manner as it does for GDPR Forget me.

There is one method available for this:

disableThirdPartySharing

Example:

Adjust.disableThirdPartySharing();

License

The Adjust SDK is licensed under the MIT License.

Copyright (c) 2020 Adjust GmbH, https://www.adjust.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.