Last modified May 23, 2019 by Shelly Wolfe

Web

Swrve is a multi-channel customer engagement platform that provides hyper-targeting and hyper-personalization in real-time to automate relevant moments of interaction that acquire, retain, and monetize customers.
The Swrve Web SDK for web browsers enables your web app to use all of these features. This guide contains all the information you need to integrate the SDK for your web app.

Requirements

The Swrve Web SDK is intended and tested for use with web browsers—mainly Chrome, Firefox, and Safari.
To use the Swrve Web SDK, you must generate a Web SDK API key in Swrve on the app’s Integration Settings screen. For more information, see Integrate your app.
The Swrve Web SDK is intended for tracking and targeting identified users across multiple channels and platforms, for example, web, mobile app, TV. Therefore, you must have your own means of generating and storing unique identifiers for the visitors of your site. For more information, see Tracking your users with Swrve User Identity.
If you download the SwrveSDK production bundle and include it via script tag, there are no additional dependencies.
If you want to compile the SDK bundle from source, you will need Node.js 8+ and Yarn 1.5+.

Installing the SDK

Swrve has an open source SDK repository. There are two options for downloading the latest public Swrve Web SDK:

Install the SDK using npm (node package manager).
Run the following command: npm install @swrve/web-sdk.
Download the SDK from the GitHub public repository.

Initializing the SDK

Depending on your data requirements, Swrve stores all customer data and content in either our US or EU data centers. If your app uses EU data storage and URL endpoints (that is, you log into the Swrve dashboard at https://eu-dashboard.swrve.com), include the EU stack information in the example below. If you have any questions or need assistance configuring the SDK for EU data storage, please contact support@swrve.com.

To initialize the SDK, create an instance before your application starts. Replace <app_id>, <web_api_key> and <external_user_id> with your app ID, Web SDK API key and unique external user ID.

The <external_user_id> is a non-discoverable key that identifies your user across multiple channels and platforms. Emails or other personally identifiable information (PIIs) are not accepted as external user IDs, they will be rejected on the server side.

Using the SDK bundle with a script tag

<script src="SwrveSDK.js"></script>
<script>
    SwrveSDK.default.createInstance({
        appId: <app_id>,
        apiKey: "<web_api_key>",
        externalUserId: "<external_user_id>",
        //stack: "eu", **To use the EU stack, include this in your config **//
    });
</script>

SwrveSDK.default.createInstance({

appId: <app_id>,

apiKey: "<web_api_key>",

externalUserId: "<external_user_id>",

//stack: "eu", **To use the EU stack, include this in your config **//

});

</script>

The .default is not necessary if you are using modules.

Using the SDK when installed from npm

When using ES5 modules, require the SDK as follows:

var SwrveSDK = require("@swrve/web-sdk");
SwrveSDK.createInstance({
    appId: <app_id>,
    apiKey: "<web_api_key>",
    externalUserId: "<external_user_id>",
    //stack: "eu", **To use the EU stack, include this in your config **//
});

var SwrveSDK = require("@swrve/web-sdk");

SwrveSDK.createInstance({

appId: <app_id>,

apiKey: "<web_api_key>",

externalUserId: "<external_user_id>",

//stack: "eu", **To use the EU stack, include this in your config **//

});

Or you can import it it as an ES6 module:

import SwrveSDK from "@swrve/web-sdk";
SwrveSDK.createInstance({
    appId: <app_id>,
    apiKey: "<web_api_key>",
    externalUserId: "<external_user_id>",
    //** stack: "eu", **To use the EU stack, include this in your config **//
});

import SwrveSDK from "@swrve/web-sdk";

SwrveSDK.createInstance({

appId: <app_id>,

apiKey: "<web_api_key>",

externalUserId: "<external_user_id>",

//** stack: "eu", **To use the EU stack, include this in your config **//

});

Push notifications

Use Swrve’s web push notification campaigns to send personalized messages to your website users.

Supported browsers

Swrve web push notifications are available on the following browsers and operating systems.

Browser	Android	iPhone	Mac OS X	Windows PC
Chrome	✔	✖	✔	✔
Firefox	✔	✖	✔	✔
Opera	✔	✖	✖	✖
Safari	✖	✖	✖	✖

Due to iOS limitations, we do not support web push on any browsers on iOS. Additionally, Mac OS does not support large images in web push notifications. If you include an image in your notification content, the web push still appears on Mac OS, but only includes the icon image.

Web push integration steps

This section covers how to integrate Swrve web push notifications with your website.

Our web push system makes use of service workers. These are files that run on the browser to receive particular messages and are attached to the domain. To operate successfully, the service worker file must be at the root of your website package. We provide the service worker in our package under the name SwrveWorker.js. If you are directly downloading our library, you can copy it directly in. If you are using a package manager like npm, you can include a script in your package.json to move it after a successful install.

  "scripts": {
    "postinstall": "mv node_modules/@swrve/web-sdk/dist/SwrveWorker.js SwrveWorker.js"
  },

"scripts": {

"postinstall": "mv node_modules/@swrve/web-sdk/dist/SwrveWorker.js SwrveWorker.js"

Push notification registration is disabled by default. To enable it, in the initialization config set autoPushSubscribe to true.

SwrveSDK.createInstance({
    appId: <app_id>,
	apiKey: "<web_api_key>",
	externalUserId: "<external_user_id>",
	autoPushSubscribe: true
});

SwrveSDK.createInstance({

appId: <app_id>,

apiKey: "<web_api_key>",

externalUserId: "<external_user_id>",

autoPushSubscribe: true

});

If you would prefer to start the registration yourself, do not include the autoPushSubscribe in your initialization config. Use with the following function instead:

/** In this example, we have two callback functions which can used to capture the status of the registration **/
var optionalOnSuccess = () => {
	console.log('Subscribed to push successfully');
};

var optionalOnFailure = (error) => {
	console.log('Failed to subscribe to push');
	console.error(error);
};

SwrveSDK.registerPush(optionalOnSuccess, optionalOnFailure);

/** In this example, we have two callback functions which can used to capture the status of the registration **/

var optionalOnSuccess = () => {

console.log('Subscribed to push successfully');

};

var optionalOnFailure = (error) => {

console.log('Failed to subscribe to push');

console.error(error);

};

SwrveSDK.registerPush(optionalOnSuccess, optionalOnFailure);

To unregister for push, use the following function:

var optionalOnSuccess = () => {
	console.log('unsubscribed to push successfully');
};

var optionalOnFailure = (error) => {
	console.log('Failed to unsubscribe to push');
	console.error(error);
};

SwrveSDK.unregisterPush(optionalOnSuccess, optionalOnFailure);

var optionalOnSuccess = () => {

console.log('unsubscribed to push successfully');

};

var optionalOnFailure = (error) => {

console.log('Failed to unsubscribe to push');

console.error(error);

};

SwrveSDK.unregisterPush(optionalOnSuccess, optionalOnFailure);

The notification permission prompt that appears when first registering only appears once per browser for your end user. This prompt is a browser setting and not directly related to web push. When you unregister from web push, it simply stops messages from coming to that browser. If you run registration again, the permission prompt does not appear, but the user simply starts receiving notifications again.

Sending events

The Swrve SDK automatically sends certain events and also enables you to track user behavior by sending custom events. (For a list of default Swrve events, see About segment and audience filters, Events.) In turn, you can use app-generated events to trigger in-app messages on other platforms, while both app- and server-generated events help you define segments and perform in-depth analysis.

Custom events

To send a custom event, include the below example in a method where you want to send an event to Swrve.

SwrveSDK.namedEvent({name:"custom.event_name"});

Requirements for sending custom events:

Do not send the same named event with different case. For example, if you send tutorial.start, then ensure you never send Tutorial.Start.
Use a period (.) in your event names to organize their layout in the Swrve dashboard. Each ‘.’ creates a new branch in the Event name column of the Events report, and groups your events so they are easy to locate.
Do not send more than 1000 unique named events.
Do not add unique identifiers to event names. For example, Registration.Start.ServerID-ABDCEFG
Do not add timestamps to event names. For example, Registration.Start.1454458885
Do not use the swrve.* or Swrve.* namespace for your own events. This is reserved for Swrve use only. Custom event names beginning with Swrve. are restricted and cannot be sent.

Event payloads

You can add and send an event payload with every event. This allows for more detailed reporting around events and funnels.

Notes on associated payloads:

The associated payload should be a dictionary of key/value pairs; it is restricted to string and integer keys and values.
There is a maximum cardinality of 500 key-value pairs for this payload per event. This parameter is optional, but only the first 500 payloads are displayed in the dashboard. The data is still available in raw event logs.
If you want to use event payloads to target your campaign audiences, you can configure up to 10 custom events with a maximum of 20 payloads per event for audience filtering purposes. For more information, see Targeting your audience by event payloads.

SwrveSDK.namedEvent({
     name:"custom.event_name", 
     payload : {
        key1: "value1",
        key2: "value2",
     }
});

SwrveSDK.namedEvent({

name:"custom.event_name",

payload : {

key1: "value1",

key2: "value2",

}

});

For example, if you want to track when a user starts the registration experience, it might make sense to send an event named registration.start and add a payload time that captures how much time it took the user to complete the registration.

SwrveSDK.namedEvent({
      name: 'registration.start', 
            payload: {
                time: '100',
                step: '5',
            }
        });

SwrveSDK.namedEvent({

name: 'registration.start',

payload: {

time: '100',

step: '5',

}

});

Custom user properties

The Swrve SDK sends certain user properties by default and also enables you to assign custom properties to update the user’s status. (For a full list of the default user properties, see Assigning user properties.)

For example, you could create a custom user property called premium, and then target non-premium users and premium users in your campaigns.

When configuring custom properties, the Swrve SDK only supports string values.

Example of group of user properties

SwrveSDK.userUpdate({
	premium: "true",
	level: "12",
	balance: "999",
});

SwrveSDK.userUpdate({

premium: "true",

level: "12",

balance: "999",

});

Example of date-typed user property

Use the Date object to send a DateTime user property; for example, the current date at the time of a user purchase:

SwrveSDK.userUpdateWithDate({
     name: "last_purchase",
     date: new Date()
});

SwrveSDK.userUpdateWithDate({

name: "last_purchase",

date: new Date()

});

Virtual economy events

To ensure virtual currency events are not ignored by the server, make sure the currency name configured in your app matches exactly the Currency Name you enter in the App Currencies section on the App Settings screen (including case-sensitive). If there is any difference, or if you haven’t added the currency in Swrve, the server will ignore the event and return an error event called Swrve.error.invalid_currency. Additionally, the ignored events are not included in your KPI reports. For more information, see Add your app.

If your app has a virtual economy, send the purchase event when users purchase in-app items with virtual currency.

var item = "some.item";
var currency = "gold";
var cost = 99;
var quantity = 1;
SwrveSDK.purchaseEvent({
     cost,
     currency,
     item,
     quantity
})

var item = "some.item";

var currency = "gold";

var cost = 99;

var quantity = 1;

SwrveSDK.purchaseEvent({

cost,

currency,

item,

quantity

})

In-app purchase events

To notify Swrve of an in-app purchase, use the function below. For Web, Swrve does not currently validate in-app purchases. If you want to build revenue reports for your app, you must validate the receipt on your side before sending it to Swrve. For more information on the arguments passed through, see the Swrve Events API.

Example

var rewards = {}
rewards['Gold'] = { type: 'currency', amount: 200 };
rewards['Item'] = { type:'item', amount: 100 };

SwrveSDK.iapEvent({
	rewards,
	cost: 12,
	local_currency: 'euro',
	quantity: 1,
	product_id: 'item_purchased'
})

var rewards = {}

rewards['Gold'] = { type: 'currency', amount: 200 };

rewards['Item'] = { type:'item', amount: 100 };

SwrveSDK.iapEvent({

rewards,

cost: 12,

local_currency: 'euro',

quantity: 1,

product_id: 'item_purchased'

})

Testing your integration

After you’ve completed the above, the next step is to test the integration. For more information, see Testing your integration.

Upgrade instructions

If you’re moving from an earlier version of the Web SDK to the current version, see the Web SDK upgrade guide for upgrade instructions.

Developer

Developer Documentation

Web

Requirements

Installing the SDK

Initializing the SDK

Using the SDK bundle with a script tag

Using the SDK when installed from npm

Push notifications

Supported browsers

Web push integration steps

Sending events

Custom events

Event payloads

Custom user properties

Example of group of user properties

Example of date-typed user property

Virtual economy events

In-app purchase events

Example

Testing your integration

Upgrade instructions