image


indigitall browser SDK


Contents

  1. Introduction
  2. Requirements
  3. Integration of the SDK
    1. Integration of the SDK in unsecured page
  4. Chrome setup
    1. Google Firebase console
    2. Service Worker
  5. Safari setup
  6. Firefox and Edge setup
  7. Advanced features
    1. Get DeviceID
    2. Check status
    3. Enable/Disable device
    4. Get all the interest channels
    5. Get subscribed in interest channels
    6. Subscribe/Unsubscribe a channel
    7. Queries on the browser
    8. Check if the browser is compatible
    9. Check whether or not the notifications are enabled
    10. Shared LocalStorage
  8. FAQs
    1. Do I have to have all my website in HTTPS?
    2. What happens if a user deletes data from the browser?
    3. Can I develop the local integration, without having to setup HTTPS?
    4. What type of certificate must I buy for the runway?
    5. What type of Firebase account have I buy for the notifications?
    6. If I want to give support to Safari, Do I need a new Apple Developer account?
    7. To the Apple certificate, What Website Push ID must I choose?
    8. What parameters can I asociate to the notification?

1. Introduction

This document contains all the information necessary to carry out the integration of indigitall platform in browsers compatible with the reception of notifications, currently Google Chrome (starting from version 42), Safari (from OS X10.9) and Firefox.

Since the implementation for each of the browsers is relatively different, this manual is divided into 3 parts: common implementation, specific to Chrome setup and setup for Safari on OS X.

This document is written for Web developers, so a technical language will be used when necessary, as well as examples of source code and print screens to make the follow-up of this manual easier.

2. Requirements

For the correct operation of the notifications in browsers, in addition to the correct setup of each section, in the case of Chrome and Firefox is essential requirement that the page is on a https path (avalid SSL certificate should be used, obtained through an authorized dealer, and using TLS encryption at least in the version 1.0). In addition, so that a notification is received, it is necessary that the browser is running (either on the foreground or background). On the other hand, in Safari, the notifications will be received even with the browser completely closed.

It is also important to note that, with the current implementation of remote notifications offered by Safari, the setup details cannot be modified once configured for the first time (when the user agrees to receive notifications, such setup is automatically downloaded and cannot be updated unless the user disables it and then re-enables the notifications, time in which the settings will be downloaded again). This configuration includes the icon and the URL template to open after you click on a notification (described more precisely in the section on Safari).

3. Integration of the SDK

Option 1: Configuration data in the indigitall folder: We must adapt the SDK setup that is located in the indigitall folder, in the file indigitall.json with our setup data. We must move the file service-worker.min.js to the root of the website, so it can be accessible from /service-worker.min.js.

To use the options offered by the library, first we must import from our HTML the main javascript that will give access to all the functionality.

We must incorporate the script at the end of the document (or by using the async attribute available in the HTML5 specification). In this case, to make sure that the initialization call is made at the right time, when the SDK is fully charged, we must listen to the 'indigitallReady' event. Below is an implementation example:

index.html

<!DOCTYPE html>
<html>
<head>
  <title>Ejemplo indigitall</title>
</head>
<body>
  <script>
      document.addEventListener('indigitallReady', function() {
        navigator.indigitall.loadIndigitall(function(){
            console.log('Successs!!');
          }, function(error){
            console.log('Error!! ' + error);
        });
      });
  </script>
  <script type="text/javascript"src="/indigitall/indigitall.min.js?v=x.x.x"></script>
</body>
</html>

/indigitall/indigitall.json

{
  "APP_TOKEN": "APP_TOKEN",
  "WEB_SITE_PUSH_ID": "web.com.domain",
  "ICON": "/indigitall/logo.png",
  "TITLE": "indigitall",
  "DEBUG_MODE": true,
  "VAPID_PUBLIC_KEY": "BPNci1jg-deZqNqeFdeYWodJ78bF7fsYvbbsDlgO..."
}

All the changes above are necessary to fully integrate the indigitall platform on the website; only remaining the necessary particular settings for each platform. In the setup file indigitall.json, it is necessary to indicate the following parameters:

{
  "APP_TOKEN": Application ID in the indigitall platform,

  "WEB_SITE_PUSH_ID": Website ID configured in the Apple Developer Center. Se explica con más detalle en la sección correspondiente a Safari,

  "ICON": Icono que se mostrará por defecto en chrome en caso de no enviar ningún otro asociado a la notificación (en safari se muestra el icono predefinido al configurar la aplicación),

  "TITLE": Título por defecto para las notificaciones en caso de que no se indique ningún otro al realizar el envío de la notificación,

  "DEBUG_MODE": Valor booleano (true/false) indicando si se debe imprimir por la consola web información de debug. Debe estar a true en el entorno de desarrollo y a false en el de producción,

  "VAPID_PUBLIC_KEY": String de clave pública VAPID del servidor de push. La proporciona el equipo de indigitall al crear la aplicación
}

Option 2: Configuration data in other folder.

If the indigitall.json file is saved in other folder different to indigitall folder is necessary indicate it to the SDK in the moment of the library initialization:

index.html

<!DOCTYPE html>
<html>
<head>
  <title>Ejemplo indigitall</title>
</head>
<body>
  <script>
      document.addEventListener('indigitallReady', function() {
        navigator.indigitall.loadIndigitall('/CONFIGURATION_FOLDER/',function(){
            console.log('Successs!!');
          }, function(error){
            console.log('Error!! ' + error);
        });
      });
  </script>
  <script type="text/javascript"src="/indigitall/indigitall.min.js?v=x.x.x"></script>
</body>
</html>

3.1. Integration of the SDK in unsecured page

To implement indigitall in an unsecured page, you must prepare a gateway in HTTPS. We will have 3 points, the unsecured page in a domain and another HTTPS secure domain, we will have the indigitall folder and a gateway where we will ask to the user the permissions for the notifications.

The gateway is implemented following the normal integration of the SDK. Here we will cover the configuration of the SDK on the unsecured page.

It is important to pass the Setup object, with the INDIGITALL_FOLDER, parameter, and not get confused and pass a string, because the SDK will not start as a slave, but as a separate page.

index.html

<!DOCTYPE html>
<html>
<head>
  <title>Example indigitall</title>
</head>
<body>
  <script>
      document.addEventListener('indigitallReady', function() {
        var options = {
          INDIGITALL_FOLDER: 'https://domain/indigitall/'
        };
        navigator.indigitall.loadIndigitall(options, onLoadSuccess, onLoadError);
      });

      function onLoadSuccess(newUser){
        if(newUser){
          console.log('The user does not accept web push notifications yet. Redirect him to the notification signup web');
        }else{
          console.log('The user already has web push notifications active.');
        }
      }

      function onLoadError(error){
        alert('Error!! ' + error);
      }
  </script>
  <script type="text/javascript" src="/indigitall/indigitall.min.js?v=x.x.x"></script>
</body>
</html>

The Success function receives a Boolean as a parameter that indicates if the user is new and doesn't have notifications enabled.

This function can be used directly before initializing the SDK in the following function Check whether or not the notifications are enabled as well as it is also possible to check if the browser supports notifications (although the library initialization will equally fail in this case) Check if the browser is compatible.

4. Chrome setup

4.1. Google Firebase console

This tutorial details how to obtain the FCM Server Key, necessary for the reception of notifications in Chrome.

4.2. Service worker

We have to move the file service­-worker.min.js. This file must be on the root of the page, otherwise the scope of such service worker would not be suitable to process the information for push notifications and would not be possible to carry out the exchange of information between the worker and the page; so, some of the features of the indigitall platform (concerning the use of filters and statistics) could be affected.

5. Safari setup

To make the setup in Safari, we must generate a WebsitePush ID and a WebsitePush ID Certificate (.p12 and its password). Tutorial

In addition, the developer will have to communicate to the indigitall team the allowed domains where users of the service will sign up and the icon to display in the notifications (square image, 256x256pixels).

6. Firefox and Edge setup

If the library is already properly configured to work with Chrome, no additional action is required to setup Firefox, since the reception also works when including the service worker.

7. Advanced features

In addition to the setting for the reception of notifications, the indigitall platform offers different options to enrich the user experience. In this way, as for other platforms, the subscription of categories or the cancellation of the notifications subscription is allowed. For this, the library offers the following calls.

All the features of the library are accessible through the navigator.indigitall object; through which we can access, in addition to the functions which we will discuss later, the following properties (all of them should be used only in read mode, its change has no effect on the operation of the library):

APP_TOKEN: indigitall app ID.

DEF_IMG: Default image used in the notifications.

DEF_TITLE: Default title used by the notifications.

DEVICE_ID: Device ID in the indigitall platform

PUSH_TOKEN: In Chrome, the push token obtained in the subscription to GCM

PW_ID: Application ID in the push server.

WEB_SITE_PUSH_ID: Website ID in Apple.

isChrome: Boolean property to check if the browser is Chrome.

isSafari: Boolean property to check if the browser is Safari.

isFirefox: Boolean property to check if the browser is Firefox.

In terms of functions, the library offers the calls detailed below:

7.1 Get DeviceID

When we talk about DeviceID, we refer to the unique identifier that the indigitall library generates to identify the device and send them push messages. This example indicates how to collect this data in order to work with it.

document.addEventListener('indigitallReady', function() {
  navigator.indigitall.loadIndigitall(function(){
      var device_id = navigator.indigitall.getDeviceId();
    }
  );
});

Tip: The first time DeviceID is generated when indigitall SDK loads (success callback in method loadIndigitall). Then this ID is saved in the browser LocalStorage using the key indDeviceId

7.2 Check status

indigitall library allows you to enable and disable a device, so that the possibility to disable the notifications can be offered to the user. To check the current status, there is the call: navigator.indigitall.getStatus(successCallback, errorCallback);

This call takes as parameters the callbacks in the event of success or if it finds any errors. In the event of success, the callback function will receive an object with a String type status field with the value 'enabled' or 'disabled'. In case of error, the parameter shall be a String indicating the type of error.

If you implement a window to ask the user if it wants to receive notifications or not, it must be shown if the success callback parameter has p.status == 'enabled'. In this way, we will avoid repeatedly asking the user.

7.3 Enable/Disable device

Calls that will enable or disable the device have an identical structure; and both can be called regardless of the status of the device. If you make a call to enable a device already enabled (or disable a device already disabled); an error will occur in the call and it will be indicated in the callback message. Available calls are:

navigator.indigitall.enable(successCallback, errorCallback); navigator.indigitall.disable(successCallback, errorCallback);

In both cases, in the event of success, the successCallback callback will receive a parameter with the message ‘Upgrade successful’. In the event that any problem occurs, a String with the corresponding error message will be sent to errorCallback

7.4 Get all the interest channels

As in other platforms, on the page there is the possibility of subscribing the users to interest channels created in the indigitall panel. For managing these subscription channels, the methods listed below are offered. First, the following method will get all interest channels available for the current application:

navigator.indigitall.getAllCategories(successCallback, errorCallback);

As in previous calls, the parameters will be two callbacks, for success or failure. In case of success,the function successCallback will receive as parameter an Array with all the available categories; each category being an object of the form:

{
    "id":"id",
    "name":"name",
    "parent":"id_parent"
}

In the parent field, the value will be the value id of the parent category or, in case of a root category, the string ‘#’. In case of error, the errorCallback function will receive a String with a description of the error.

7.5 Get subscribed in interest channels

In addition to the previous call, to get the labels in which our device is already signed, we have the following call:

navigator.indigitall.getSubscriptions(successCallback, errorCallback);

The use of this call is exactly equal to the previous, and the structure of the reply, both of the errorCallback as of the successCallback is identical.

7.6 Subscribe/Unsubscribe a channel

The available methods that allow you to subscribe or unsubscribe the users from the interest groups, are the following:

navigator.indigitall.subscribe(channels, successCallback, errorCallback); navigator.indigitall.unsubscribe(channels, successCallback, errorCallback);

In this case, in addition to the usual callbacks; It is necessary to indicate the channels to which we want to make or delete the subscriptions. The way to indicate them will be through an array of tag IDs, for example:

Several: [“identificador1”, “identificador2”]; Only one: [“identificador1”];

Both a as b would be valid variables for the subscribe/unsubscribe call. It is important that, although the subscription or unsubscription is to a single category, this must be sent within an array; otherwise an error occurs and an errorCallback will always be called.

7.7 Queries on the browser

The variables navigator.indigitall.isChrome, navigator.indigitall.isFirefox and navigator.indigitall.isSafari will be used to distinguish the browser of the client. You can also use the function navigator.indigitall.isAppleMobile() that comes back true when the client is an iPhone or an iPad. These variables and functions are very useful to customize the client's experience. The notification service is not available for iPhones/iPads. These functions are a solution to display subscription messages only to supported clients.

7.8 Check if the browser is compatible

The function navigator.indigitall.browserSupported() that returns a Boolean indicating whether the browser supports notifications or not is available.

7.9 Check whether or not the notifications are enabled

The function navigator.indigitall.notificationsActive() returns a Boolean if the notifications are enabled for the user. If they are not enabled, it may be due to several reasons, like the user has no DeviceID, because the cookies have been deleted, or it does not have notification permissions.

7.10 Shared LocalStorage

The function navigator.indigitall.write(key, value, callback) te permite escribir un registro en el local storage de la pasarela, accesible desde cualquier web no segura que inicialice el SDK de indigitall y que apunte a la misma pasarela.

La función navigator.indigitall.write(key, callback) allows you to write a record in the local storage of the gateway, accessible from any unsecured page that initializes the indigitall SDK and points to the same gateway.

8. FAQs

Do I have to have all my website in HTTPS?

For security requirements, both Chrome as Firefox require that the permission request is made in a domain that runs under HTTPS. It is not necessary that all the website is in HTTPS, only the page that performs the call to loadIndigitall, which is responsible for launching the permission request prompt and install the service that listens to the notifications in the background.

What happens if a user deletes data from the browser?

When a user deletes data in Chrome or Firefox, uninstalls the Service Worker, which is responsible for listening in the background the receipt of notifications. To install it again in your browser it is necessary to load the page where the so-called aloadIndigitall runs. This installation is completely transparent to the client, i.e., it does not launch again the browser prompt to ask for permissions. For this reason, we recommend the call to loadIndigitall to be made, if possible, on a “passage” page (like the home of our website).

Can I develop the local integration, without having to setup HTTPS?

Yes, it is possible. Although it does not run in HTTPS, Chrome and Firefox make a “security exception” with localhost, to make the development tasks easier. In the case of Safari, Apple verifies if the domain from which you ask the permissions is in the list of allowed domains. Email us at soporte@indigitall.net so that we add 127.0.0.1, and deploy to port 80 on the localhost. Note: to test in Safari, you have to access domain 127.0.0.1, not a localhost.

What type of certificate must I buy for the runway?

Any certificate is valid for web. If you do not have a provider, we recommend: Let's Encrypt.

Let’s Encrypt is a free, automatized and open Certification Authority (CA), that is executed for the Internet Security Research Group (ISRG). This make possible the obtaining of trusty browser certificates for yours domains without cost. Moreover this certificates are renovated each 90 days automatically. With Let’s Encrypt there is not complicated configurations, validation emails and you can have multiples certification install in your hosting accounts for each domain and subdomain that your choose. The certificates are domain-validated, it does not require a IP dedicated direction and is valid to the main browsers.

In internet you will find multiple guides and tutorials to install a certificate with Let's Encrypt, here you have one: Guide Let's Encrypt.

What type of Firebase account have I buy for the notifications?

Any account is valid, if you have an payment account, you can use it. For the opposite if you do not have one, you can use a free account FireBase Prize.

If I want to give support to Safari, Do I need a new Apple Developer account?

With only one Apple Developer account, you can work the App iOS part and the Safari part. In this sense the account has to be a payment account to can generate the certificate. If the account is not a payment account the 'Certification' tab will not appear.

To the Apple certificate, What Website Push ID must I choose?

We recommend that the Website Push ID is the domain of website upside down, but it can be any that is not being used.

What parameters can I asociate to the notification?

  • Title
  • Body
  • Image
  • URL

Is possible set aditional parameters in the URL using QueryString.