Web

Numeric value

ll('setProfileAttribute', 'Age', 45, 'org');

Numeric values in a set

ll('setProfileAttribute', 'Lucky Numbers', [8, 12], 'app');

Date value

ll('setProfileAttribute', 'Last Purchase Date', new Date(), 'org');

Date values in a set

ll('setProfileAttribute', 'Upcoming Milestone Dates', [new Date('2015-10-01'), new Date('2016-03-14')], 'app');

String value

ll('setProfileAttribute', 'Hometown', 'New York, New York', 'org');

String values in a set

ll('setProfileAttribute', 'States Visited', ['New York', 'California', 'South Dakota'], 'app');

Adding a numeric value to a set

ll('addProfileAttributesToSet', 'Lucky numbers', [8], 'app');

Adding a date value to a set

ll('addProfileAttributesToSet', 'Upcoming Milestone Dates', [new Date('2015-04-19')], 'org');

Adding a string value to a set

ll('addProfileAttributesToSet', 'States visited', ['North Dakota'], 'app');

Removing numeric values from a set

ll('removeProfileAttributesFromSet', 'Lucky numbers', [8, 9], 'org');

Removing date values from a set

ll('removeProfileAttributesFromSet', 'Upcoming Milestone Dates', [new Date('2016-03-14')], 'app');

Removing string values from a set

ll('removeProfileAttributesFromSet', 'States visited', ['California'], 'org');

Basic Integration

Basic integration allows for the simplest and easiest way to integrate the Localytics Web SDK with web push. Opting for basic integration will minimize your required changes while still providing all the benefits of web push.

To get started, first update your initialization options with the workerPath, workerName, and publicKey like the following:

ll('init', 'YOUR_APP_KEY', {
  workerPath: '/', 
  workerName: 'worker.js',
  publicKey: 'YOUR_PUBLIC_KEY_AS_PROVIDED_TO_LOCALYTICS_DASHBOARD'
});
      

Fill out each key with the appropriate values. These values will be discussed more in depth in the following sections on service workers and web push certificates.

Next, you will have to ask your users for permissions to deliver them notifications. In the basic integration this is as simple as a single API call:

ll('registerPush', 
  () => console.log('Successfully registered for push!'), 
  (e) => console.error('Failed to register for push', e))
);
      

This method will fail if the publicKey, workerPath or workerName provided during initialization are invalid or missing. However, if everything is valid, this method will register the service worker with the browser, prompt your users for permission to display notifications, and store a push token within Localytics if that prompt was accepted. This method is safe to call on every session. If any of the steps have been previously completed, they will be a no-op on subsequent calls.

Advanced Integration

Advanced integration allows requires a slightly more complex approach, but provides much more flexibility. Opting for advanced integration may be right for you if you have multiple push providers on the web, or you prefer to have more control over the service worker registration and push prompt.

Regardles of how you prefer to register your service worker or prompt the user, the Localytics SDK will always need to be initialized with the workerPath, workerName, and publicKey like the following:

ll('init', 'YOUR_APP_KEY', {
  workerPath: 'YOUR_WEB_SERVICE_WORKER_HOST', 
  workerName: 'YOUR_WEB_SERVICE_WORKER_FILE_NAME',
  publicKey: 'YOUR_PUBLIC_KEY_AS_PROVIDED_TO_LOCALYTICS_DASHBOARD'
});
      

Fill out each key with the appropriate values. These values will be discussed more in depth in the following sections on service workers and web push certificates.

Next, you will have to register the service worker. This can be accomplished using standard methods, but Localytics provides a convenience method to help you accomplish that:

ll('registerServiceWorker', 
  (swRegistration) => console.log('Successfully registered service worker!'), 
  (e) => console.error('Failed to register service worker', e)
);
      

Registering the service worker has no visible impact or effect to the end user, so regardless of how you intend to prompt your users, we suggest that you always register your service worker at the beginning of your session.

Once you have registered a service worker, you can then prompt the user for push permissions. This can also be accomplished using standard methods, but Localytics provides another convenience method:

ll('subscribeToWebPush', 
  (subscription) => console.log('Successfully retrieved a push token!'), 
  (e) => console.error('Failed to register for a push token - the user may have denied the permission', e)
);
      

Calling this method will show the user the browser prompt if they haven't previously seen it. Assuming they accept the prompt, the success callback will be called with the push subscription. If there is any error, or the user has denied permissions, the failure callback will be called. If you prefer to use the standard methods provided by the browser, make sure to call this method as well. If you don't, Localytics may not be able to retrieve the push subscription until the following session.

All of the above methods rely on the publicKey, workerPath and workerName provided during initialization to be present and valid. If everything is valid, this process will register the service worker with the browser, prompt your users for permission to display notifications, and store a push token within Localytics if that prompt was accepted. For each step, if any of the steps have been previously completed, they will be a no-op on subsequent calls.

Basic Integration

In the basic integration, we suggest you take advantage of the Localytics service worker to handle all of the aforementioned steps. Create a new file named worker.js and in it include the following code:

self.appKey = 'YOUR_APP_KEY';
self.importScripts('https://web.localytics.com/v4/worker.js');
      

Make sure to replace YOUR_APP_KEY with your web page's app key. This service worker will handle tagging performance events, receiving push messages, rendering notifications, and deeplinking. Serve this file from the root of your domain.

Finally, update the initialization of the Localytics SDK as appropriate:

ll('init', 'YOUR_APP_KEY', {
  workerPath: '/', 
  workerName: 'worker.js',
  publicKey: 'YOUR_VAPID_PUBLIC_KEY_AS_DEFINED_IN_LOCALYTICS_DASHBOARD'
});
      

Advanced Integration

In advanced integration, you will prefer to create and serve your own service worker. Following the next steps, you will be able to integrate Localytics fully into the service worker:

1. Import and initialize the Localytics SDK into the service worker:

   importScripts('https://web.localytics.com/v4/localytics.min.js');
   Localytics.initFromServiceWorker('YOUR_APP_KEY', {});
             
   

2. Register a callback for when a push notification is delivered to the browser. This callback allows you the opportunity to render the notification that came in. There are two possible approaches to rendering the notification:

   1. The first approach allows Localytics to handle the notification entirely. If this notificaton originated from the Localytics system, the notification will be rendered and a Localytics Push Received event will be tagged:

      self.addEventListener("push", event => {
        try {
          const success = Localytics.handleNotificationReceived(event);
          if (!success) {
            console.log('Failed to render push notification');
          }
        } catch (err) {
          console.error("Unable to render push notification", err, event);
        }
      });
                    
      

   2. The second approach has Localytics parse the payload. If the push originated from the Localytics system, Localytics Push Received will be tagged and a proper payload will be returned. If not, then an empty object will be returned. You can then modify the push payload as you like, but for simplicity, this sample will render the notification:

      self.addEventListener("push", event => {
        try {
          const {title, ...rest} = this.parseNotification(event.data.json());
          if (title) {
            // this push originated in the Localytics system.
            self.registration.showNotification(title, { ...rest });
          }
          // this push did not originate in the Localytics system - handle it yourself.
        } catch (err) {
          console.error("Unable to render push notification", err, event);
        }
      });
                    
      

3. Register a callback for when a push notification is opened by the user. This callback allows you the opportunity to determine how to act upon the user interaction. Once again there are two ways this integration can be handled:

   1. The first approach allows Localytics to handle the event entirely. Pass the event to Localytics and allow Localytics to tag Localytics Push Opened as well as handle deeplinking:

      self.addEventListener("notificationclick", (event) => {
        event.notification.close();
        var success = Localytics.handleNotificationOpened(event);
        if (success) {
          // Localytics handled the notification
        }
        // Localytics could not handle the notification.
      });
                    
      

   2. The second approach prevents Localytics from doing it's default deeplinking. Use this approach if you would like to add some custom logic to your deeplinking behavior, but make sure to always attempt to tag Localytics Push Opened. In this example we just allow the event to open the original webpage:

      self.addEventListener("notificationclick", (event) => {
        event.notification.close();
        Localytics.tagPushOpened(event);
        event.waitUntil(
          clients.openWindow(self.location.origin)
        );
      });
                    
      

4. Register a callback for when the push subscription has changed. This will allow Localytics to keep the push subscription up to date, and ensure the user stays push addressable:

   self.addEventListener('pushsubscriptionchange', e => {
     e.waitUntil(self.registration.pushManager.subscribe(e.oldSubscription.options)
       .then(subscription => {
         Localytics.savePushSubscription(subscription)
       }));
   });
             
   

Finally, save this file as worker.js, serve if from the root of your domain, and update the initialization of the Localytics SDK as appropriate:

ll('init', 'YOUR_APP_KEY', {
  workerPath: '/', 
  workerName: 'worker.js',
  publicKey: 'YOUR_VAPID_PUBLIC_KEY_AS_DEFINED_IN_LOCALYTICS_DASHBOARD'
});
      

Opting users out

Many apps may allow their users the ability to opt out of data collection. In order to stop the Localytics SDK from collecting any additional data, customers can call:

ll("setOptedOut", true);

Any device that has opted out in Localytics will immediately close the current session (if there is one) and tag an opt out event indicating that the device is no longer reporting any future data. Any subsequent calls that would generate a datapoint (tagEvent and setProfileAttribute for example) will be dropped. Additional detail is available in this Localytics Help article.

The opt out setting in Localytics is device specific, so if your app supports multiple users, you may want to trigger a call to setOptedOut every time a user logs in or out to update the Localytics SDK based on their previous preference.

Methods to support GDPR and other privacy requirements

You will be expected to set the privacy status of end users when they enter your website or are authenticated. setPrivacyOptedOut API facilitates setting privacy status.

• ll('setPrivacyOptedOut', true) This API will result in the deletion of all the end user's data in addition to halting collection of that users data going forward.

An example of opting out a user is included below.

var optedOut = false;
// make a request to your servers to retrieve the end user's customer id and opted out status.
ll('setCustomerId', customerId)
ll('setPrivacyOptedOut', optedOut);