Initial SDK setup

Minimum setup

To get started, you need to perform the following tasks:

Supported browsers

FollowAnalytics SDK supports Web Analytics and sending Web Push Notifications to desktop or mobile browsers. Web Analytics works on the following browsers:

Web Push Notifications works on the following browsers:

Chrome, Firefox, Opera (both on Desktop and Android)

Future versions of the SDK will support Safari Push Notifications.

Install and configure with your API key

Prepare your API key

Be sure to have your API key for this step of the configuration. If you are not sure where to find it, please reach out to your Customer Success Manager or message support@followanalytics.com

  1. Download the SDK.

  2. Place the downloaded fa-sdk-web.js and fa-sw-webpush.js in your site's root.

  3. Copy this snippet into the <head></head> of your site/application and everywhere you want to use the FollowAnalytics Web SDK:

    <script type="text/javascript" src="/fa-sdk-web.js"></script>
    <script type="text/javascript">
        FollowAnalytics.initialize({
            FAID: '<YOUR_API_KEY>',
            bundleId: '<YOUR_BUNDLE_ID>'
        });
    </script>

Replace <YOUR_API_KEY> and <YOUR_BUNDLE_ID> with the API Key and Bundle ID you got from the Administration section on the FollowAnalytics platform.

You can pass a defaultIcon value to the initialize method to make sure your Push Notifications have an icon displayed by default. You can override this defaultIcon on a per-message basis from the Campaign creation section. Example usage of the defaultIcon parameter:

    :::html
    <script type="text/javascript" src="/fa-sdk-web.js"></script>
    <script type="text/javascript">
        FollowAnalytics.initialize({
            FAID: '<YOUR_API_KEY>',
            bundleId: '<YOUR_BUNDLE_ID>',
            defaultIcon: 'https://s3-eu-west-1.amazonaws.com/fa-sdks/sdk-web/web-sdk-assets/followanalytics192.png'
        });
    </script>

Service Worker

After downloading and extracting the FollowAnalytics Web SDK, you'll have a file named fa-sw-webpush.js. This file must be uploaded to the root of your site, so that it can be accessed by going to https://you_website.com/fa-sw-webpush.js. This is mandatory in order for Notifications to work.

Integrating with an existing Service Worker

As there can only be one Service Worker registered per domain, you'll have to load FollowAnalytics' Service Worker from inside your existing one. Save the downloaded fa-sw-webpush.js right next to the existing Service Worker file and add the following at the end: importScripts("./fa-sw-webpush.js");.

Caching

With the increase of Progressive Web Apps you may run into problems when updating the SDK files on your site. Please make sure you properly invalidate the cache for the SDK files after you update them. Otherwise, it may lead to unexpected results.

Register for notifications

Web push notifications require HTTPS

Web push notifications can only be sent if your web domain is accessible through HTTPS.

Optimize your subscription rate

You should explain to your visitors the benefit of registering to your notifications before prompting them the popup which formally collects the permission. A user is much more likely to accept notifications if they know what they will receive, how frequently, and so on.

A push notification is a message that appears on the user’s screen and can be received even when your web page is not currently open in the user's browser.

In order for your Web Push Notifications to work, you must register it by calling:

FollowAnalytics.registerForPushNotifications();

If a user wants to unsubscribe from Web Push Notifications, you can do so by calling:

FollowAnalytics.unregisterFromPushNotifications();

To check if a user is already registered for Push Notifications you can use the following method:

FollowAnalytics.isRegisteredForPushNotifications();

Logging

Logging best practices

To ensure your tags are relevant and will end up empowering your team through FollowAnalytics, please read the Logging best practices entry in the FAQ section.

Events vs Attributes

The FollowAnalytics SDK allows you to tag both events and attributes. If you are unsure about the difference, please refer to the corresponding FAQ entry.

Tag Events

The SDK allows you to log events happening in your code. These are the two methods you can call on the SDK:

FollowAnalytics.logEvent(name, arg)
FollowAnalytics.logError(name, arg)

Use the name as the unique identifier of your tag, use the details section to add context. Events can be renamed later: the name that you give to your event here can be overridden in the FollowAnalytics UI.

The details field can either be a String or a Hash, so that you can associate multiple key-values for additional context.

For instance, logging the appearance of a view could be done as the following examples:

FollowAnalytics.logEvent('Product view', 'Product reference')

var details = {firstParam: 'My first object detail', secondParam: 'My second object detail'}
FollowAnalytics.logEvent('Example log name', details)

User ID

If users can sign in somewhere in your web app, you can specify their identifier to the SDK. This way, you will be able to build a profile in FollowAnalytics, send transactional campaigns, link your users with your other apps and even between FollowAnalytics and your CRM, and more.

This identifier is usually an e-mail address, client identifier, phone number, or anything else that uniquely ties your customers to you.

To register the user identifier, use:

Javascript

FollowAnalytics.setUserId(userId)

If you want to remove the user identifier (in case of a sign out for instance) use the following method:

FollowAnalytics.setUserId(null)

You can get the current user ID set by calling:

FollowAnalytics.getUserId()

Advanced use cases

Device ID

You can get your device ID, which is a unique identifier generated on the very first use of the SDK, and stored in local storage. As long as the user doesn't delete their local storage data, this value will prevail.

FollowAnalytics.getDeviceId()

This method will return a string containing the deviceId value.

Optional initialization parameters

When initializing the SDK in your web app, you can pass the following parameters to customize its behavior: