SDK

Implementation

If you've completed the steps described in the Setup guides, you are now ready to implement our HTML 5 library in your app. Our library supports Chrome 59 and higher (desktop) and Chrome 61 (Android) and higher, Opera 47 (desktop & Android) and higher, Firefox 54 (desktop & Android) and higher and Safari on MacOS 10.9 and higher.

If you are upgrading from an older version of our library, it's always a good idea to read the Migration file.

Download Library

Our HTML 5 library is distribute as a JS library or a WordPress plugin. In this document we will cover the implementation of the JS library in a web server but some of these instructions will also apply for an advanced WordPress setup.

Developing in localhost

For your convenience, while developing in your local machine, we have included a simple web server using Node.js. You can of course skip this if you already have a local development environment or you are implementing it in your own web server. Extract the contents of the JS library to any place in your computer, then open your terminal and navigate to that directory. Assuming that you have already installed Node and NPM, in the root of that directory, type the following:

npm install

This will install as the module dependencies so you can run a local server for testing purposes. After this you should be able to run the project by typing the following:

node server

If everything is ok, you should be able to see it at http://localhost:3333. If you are using it in your own server, copy the contents of the public/ folder to a publicly accessible directory in your server. Then simply access that location to see it in action. Please note that service workers require HTTPS when served from a web server.

Start Implementing

First, make sure you have included a reference to the library just before the closing body tag:

<script src="/notificare.min.js"></script>

Optionally you can also use our own hosted solution, for that, use the following just before the closing body tag:

<script src="https://cdn.notifica.re/libs/html5/v2/latest/notificare.min.js"></script>

Or if you prefer to have control over the version you are using, use the following just before the closing body tag:

<script src="https://cdn.notifica.re/libs/html5/v2/2.4.0/notificare.min.js"></script>

In order to support Chrome legacy browsers, you will need to include a Web App Manifest file, if you do not, push notifications will not work for older Chrome versions. If you want to support older versions of Chrome, and you do not yet have a manifest file in your website, make sure you copy this one and save its contents in a file called manifest.json in the root directory. Then in your html page, add the following line between your opening and closing head elements:

<link rel="manifest" href="/manifest.json" />

You can also learn more about Web App Manifest files here.

Finally, open that Web App Manifest and make sure you replace its contents with your own data:

{
    "name": "Website Push",
    "short_name": "Website Push",
    "display": "standalone",
    "gcm_sender_id": "YOUR SENDER ID",
    "gcm_user_visible_only": true
}

It's important that you add the gcm_sender_id which should be the Sender ID found in the Firebase Developer Console, this is covered in the Setup guides.

fcm cloud messaging keys

Please note that the manifest.json is not mandatory, if you do not plan to support older versions of Chrome.

Finally you need to make sure you add the service worker file located in public/sw.js in your root directory. This will be the file that makes your website receive notifications even when it is not opened. Learn more about Service Workers files here.

Configuration

Our library by default will lookup for a file named config.json in your root directory. This file will carry the basic configuration needed to use the library. Make sure you replace all the data to match your own:

{
    "appHost": "YOUR_DOMAIN_HERE",
    "appVersion": "1.0",
    "appKey": "YOUR_APP_KEY_HERE",
    "appSecret": "YOUR_APP_SECRET_HERE",
    "ignoreNonWebPushDevices": false,
    "allowOnlyWebPushSupportedDevices": false,
    "serviceWorker": "sw.js",
    "serviceWorkerScope": "./",
    "googleMapsAPIKey": "PUT_GMAPS_KEY_HERE",
    "geolocationOptions": {
        "timeout": 60000,
        "enableHighAccuracy": true,
        "maximumAge": 100000
    }
}

Initializing the Library

Now let's initialize the Notificare library, in all the pages you want to add this functionality, make sure you add a javascript snippet like this, just before the closing body and after the all the reference to the notificare.min.js:

<script>
    document.addEventListener("DOMContentLoaded", () => {

        //This instantiates the library
        const notificare = new Notificare();

        ... more code
    });
</script>
Please note that our examples use Javascript's ES6 syntax. This is not supported by all browsers. If you are targeting older browsers (specially Internet Explorer) you will want to use the ES 5th Edition syntax to make sure this code does not generate errors.

After this point, you have instantiated the Notificare library and consequently you can use the notificare instance to further interact with the library. Keep reading our Implementation guides to dive deeper into all the features included in this library.