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>

OptInAnalytics

You can configure the default state of analytics collection for your site or web application using the initialization parameter optInAnalytics.

When set to false no analytics data will be collected. You can change this at runtime by using FollowAnalytics.setOptInAnalytics(true).

Example, starting with no analytics collection:

    :::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'
            (...),
            optInAnalytics: false
        });
    </script>

In order to enable analytics, call FollowAnalytics.setOptInAnalytics(true) from anywhere in your code.

Analytics Scope

You can configure the scope of the analytics for your site or web application by using the initialization parameter analyticsScope.

This method accepts 'FULL' or 'PUSH' as a value. When you chose 'PUSH' analytics collection will only take place if the user registers for Notifications. When the scope is set to 'FULL' analytics collection will take place, not depending of the user Notification acceptance.

You can only change this while in development. In order to change it you'll have to redeploy your code.

Example, starting with full analytics collection:

    :::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'
            (...),
            analyticsScope: FollowAnalytics.AnalyticsScope.FULL
        });
    </script>

Or if you want to only collect analytics when the User registered for Notifications:

    :::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'
            (...),
            analyticsScope: FollowAnalytics.AnalyticsScope.PUSH
        });
    </script>

GDPR and Privacy

To support privacy regulations, most notably GDPR, the EU’s General Data Protection Regulation as well as our customers’ privacy policy requirements, FollowAnalytics provides the methods to assist you in these obligations.

The following methods are available in the SDK:

    :::javascript
    FollowAnalytics.GDPR.requestToDeleteMyData()
    FollowAnalytics.GDPR.requestToAccessMyData()

Both methods will only work if a userId is set for the current session.

FollowAnalytics.GDPR.requestToAccessMyData() - sends a request to FollowAnalytics' servers to download all user data for the current application.

FollowAnalytics.GDPR.requestToDeleteMyData() - sends a request to FollowAnalytics' servers to delete all user data for the current application.

Both these methods return a Promise. You can used them as follows:

    :::javascript
    FollowAnalytics.GDPR.requestToDeleteMyData().then(function(result) {
        // successfull request
        console.log(result);
    }).catch(function(error) {
        // request failed
        console.log(error);
    });
    FollowAnalytics.GDPR.requestToAccessMyData().then(function(result) {
        // successfull request
        console.log(result);
    }).catch(function(error) {
        // request failed
        console.log(error);
    });

Data Wallet

The Data Wallet feature, available from FollowAnalytics' platform, allows our clients to create , edit and publish policies : Legal text, Data sources, Purposes.

In order to make these data available from our SDK te following ethods were added:

    FollowAnalytics.DataWallet.getPolicy()
    FollowAnalytics.DataWallet.isRead();
    FollowAnalytics.DataWallet.setIsRead(true);

FollowAnalytics.DataWallet.getPolicy() - fetches the current privacy policy for the application from the FollowAnalytics platform.

FollowAnalytics.DataWallet.isRead() - allows you to check the state of the current privacy policy.

FollowAnalytics.DataWallet.setIsRead() - specifies the read state for the current privacy policy. After it has been read, call the method to mark it as read.

You can configure the SDK with the following parameters:

    isDataWalletEnabled: true,
    onDataWalletPolicyChange: function() {},

isDataWalletEnabled: true - allows you to enable/disable the DataWallet features.

onDataWalletPolicyChange: function() {} - this parameter requires a callback function and the implementation of a listener for the Policy change.

An example would be:

    <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'
            (...),
            isDataWalletEnabled: true,
            onDataWalletPolicyChange: function() {
                                        if (confirm('Privacy Policy has changed')) {
                                            // User has read the Privacy policy (clicked OK). Mark it as read
                                            FollowAnalytics.DataWallet.setIsRead(true);
                                        } else {
                                            // User has not read the policy (clicked cancel)
                                        }
                                      },
        });
    </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: