Implementation

If you've completed the steps described here and here, you are now ready to implement our Web SDK in your app. Please don't forget to read the browser support table available here.

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 library is distributed as a JS library. In this document we will cover the implementation of the JS library in a local web server.

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 to note that the gcm_sender_id which should be the Sender ID found in the Firebase Developer Console, this is covered in the Setup guides. This is only needed when you want to support older version of Chrome.

Another important part of the manifest.json, is the display property. This property must be defined as standalone if you want to support web push in iOS devices running iOS 16.4 or higher.

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 allows your website receive notifications even when it is not opened. Learn more about Service Workers files here.

Configuration

Our library by default will look up 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>

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.