Website SDK

Website SDK Overview

To get Gravitec Push Notifications running on your website, follow these two steps.

Requirements

W3C Web Push Notifications are currently supported by Chrome 50+, Opera 42, Firefox 44+, Safari 7.0+, Yandex 16.3+.

This includes Chrome for Windows, Mac OSX, Linux, Chrome OS and Android. Chrome for iOS is not yet supported by Google.

Follow our Website SDK HTTPS Installation guide if your website uses an HTTPS connection.
Or follow our Website SDK HTTP Installation guide if your website is Non-HTTPS. (Uses an HTTP connection).

Website SDK HTTPS Installation

Gravitec SDK Installation for Chrome websites (desktop + mobile)

Requirements

W3C Web Push Notifications are currently only supported by Chrome 42+

Includes Chrome for Windows, Mac OS X, Linux, Chrome OS, and Android. Chrome for iOS is not yet supported.

HTTP and HTTPS

If some of your pages are served via HTTP instead of HTTPS, then you will need to follow our HTTP Installation Guide instead.

If possible, we encourage you to migrate all your pages to HTTPS first, and then continue using this guide.

1. Download the SDK

1.1 Download the latest version of Gravitec Chrome Web SDK after the registration of your site in the Gravitec Dashboard.

1.2 Copy push-worker.js and manifest.json from gravitec_sdk_ directory and paste it into the top-level directory (root folder) of your site.

2. Include Required Files

2.1 Link https://cdn.gravitec.net/storage/APP_KEY/client.js and manifest.json to each page of your website by adding some code between <head> and </head> tags. Update APP_KEY with your Gravitec AppId. Most likely, you will have to do it just once in the file, which helps to generate a layout of the site. The resulting HTML should look like this:

<head>
 <script src="https://cdn.gravitec.net/storage/APP_KEY/client.js" async></script>
</head>

Now user will see a window asking for permission to receive notifications from your site immediately after opening the page:

3. Customize Gravitec (Optional)

3.1 Your custom button or event.

Call Gravitec.push(["init"]) from a javascript file that is included in every page. Create or use your button and update YOUR_CUSTOM_BUTTON_ID with your button id.

The user will see a window asking for permission to receive notifications from your site immediately after clicking on the button.

You can create your own logic and call registerPush() method.

Important

You must keep all the SDK files together. https://cdn.gravitec.net/storage/APP_KEY/client.js, push-worker.js and manifest.json must be placed in the root directory of your site.

Link to https://cdn.gravitec.net/storage/APP_KEY/client.js must be added between <head> and </head> tags for every page on your website. Linking files this way allows us to be sure that: - any page can subscribe to notifications - any page can be opened from a notification (if set) - changes to the Google Registration id can be updated - session count can be accurately calculated.

That's It!

That’s it for now - the setup is complete. See our Web SDK API for more functions.

var Gravitec = Gravitec || [];
Gravitec.push(["init", {"autoRegister":false}]);
window.onload = function(){
 //Replace YOUR_CUSTOM_BUTTON_ID with your button id
 document.getElementById("YOUR_CUSTOM_BUTTON_ID").onclick = registerPush;
 function registerPush() {
  Gravitec.push(["registerUserForPush", function(success){
   if (success) {
    //your custom action
   }
  }]);
 }
}

Website SDK HTTP Installation

Gravitec SDK Installation for Chrome websites (desktop + mobile)

HTTP vs. HTTPS

This is the guide for using Google Chrome push notifications on websites that have some pages served via HTTP instead of HTTPS.

If you are sure that each page is served only via HTTPS, then you should follow Website SDK HTTPS Installation guide.

Requirements

W3C Web Push Notifications are currently only supported by Chrome 42+

Includes Chrome for Windows, Mac OS X, Linux, Chrome OS and Android. Chrome for iOS is not yet supported by Google.

1. Include Required GravitecSDK.js

1.1 Include https://cdn.gravitec.net/storage/APP_KEY/client.js in the the <head> HTML tag of each of your website pages. Update APP_KEY with your Gravitec AppId. The best way is to add it to the code that generates the layout for each of your webpages. The resulting HTML should look like this:

<head>
 <script src="https://cdn.gravitec.net/storage/c98ddb5b4e54032b1f012127a3c5aec3/client.js/" async></script>
</head>

2. Customize Gravitec (Optional)

2.1 Init with your custom button or event.

Call Gravitec.push(["init"]) from a javascript file that is included in every page. Create or use your button and update YOUR_CUSTOM_BUTTON_ID with your button id.

That's It!

That’s it for now - the setup is complete. See our Web SDK API for more functions.

var Gravitec = Gravitec || [];
Gravitec.push(["init", {"autoRegister":false}]);
window.onload = function() {
 //Replace YOUR_CUSTOM_BUTTON_ID with your button id
 document.getElementById("YOUR_CUSTOM_BUTTON_ID").onclick = registerPush;
 function registerPush() {
  Gravitec.push(["registerHttp");
 }
}

Website SDK API

JavaScript Async

The example assumes that you have the following code placed defined before calling Gravitec functions.

Update APP_KEY with your Gravitec AppId.

<script src="https://cdn.gravitec.net/storage/APP_KEY/client.js" async></script>
<script>var Gravitec= Gravitec || [];</script>

List of Functions

- init

- registerUserForPush

- segmentation.addTag

- segmentation.addTags

- segmentation.setTags

- segmentation.removeTag

- segmentation.removeAllTags

- getTags

- segmentation.setAlias

- getSubscriptionData

Functions

init

This is the only required method that you need to call for setting up Gravitec to receive push notifications. Call it from each page of your site.

Parameters
JSON options
Boolean autoRegister (Optional) - Automatically show browser prompt to accept notifications. You can pass in "false" to delay this pop-up and then call registerUserForPush to prompt them later.
Boolean createButton (Optional) It creates a default button that generates a window for receipt of the notifications, which appears after clicking.
String tooltipText (Optional, use only with createButton) - Default: "One click subscription to our newsletter!" Set the text that will be shown to users on a default button.

Example:

var Gravitec = Gravitec || [];
Gravitec.push(["init", {"autoRegister":false}]);

registerUserForPush

Call it when you want to prompt the user to accept push notifications. Only call if you set "false" in autoRegister: when called "init".

Example:

var Gravitec = Gravitec || [];
Gravitec.push(["registerUserForPush", callback]);

segmentation.addTag

The method tags a subscriber basing on on app event of your choice, so that later you will be able to create segments to target users with the tag. It is recommended to use addTags rather than addTag if you need to add more than one tag in one operation.

Parameters:

string value - set this to addTag.
string value - value to set – tag name.
Call back - set here call back to be fired when tag was successfully added and response from our server has been returned.
Call back - set here call back to be fired, when tag was not added or error.

When error is encountered, err object is returned:

{ 
  error:true,  
  message: 'something went wrong' 
}

Example 1:

First call back is called when tag has been successfully added, second call back is called if some error has occurred during a tag addition:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.addTag","Tag1", 
  function() {console.log("Tag has been added")}, 
  function(err) console.log(err.message)
}])

Example 2:

Call back is called when tag has been successfully added:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.addTag", "Tag1",
  function() {console.log("Tag has been added")
}])

Example 3:

Without call back functions:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.addTag", "Tag1"
])

segmentation.addTags

Add provided tag(s) to subscriber’s tags. Thus, a push segment based on these tags could be created.

Parameters:

string value - set this to addTags.
Array of strings - JSON array of string value(s) – tag(s) to add.
Call back - set here call back to be fired when tag was successfully added and response from our server has been returned.
Call back - set here call back to be fired when tag was not added or error occured

When error is encountered, err object is returned:

{ 
  error:true,  
  message: 'something went wrong' 
}

Example 1:

First call back is called if tags have been successfully added, second call back is called if error has occurred during tags addition:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.addTags", [“new”,”new1”,”new2”], 
  function() {console.log("Tags has been added")}, 
  function(err){console.log(err.message)
}])

Example 2:

Call back is called if tags have been successfully added:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.addTags",[“new”,”new1”,”new2”],
  function() {console.log("Tags has been added")
}])

Example 3:

Without call back functions:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.addTags", [“new”,”new1”,”new2”]
])

segmentation.setTags

Clear all existing user tags and set new tags for the user.

Parameters:

string value - set this to setTags.
Array of strings - JSON array of string value(s) – tag(s) to set.
Call back - set here call back that to be fired when tag was successfully added and response from our server has been returned.
Call back - set here call back to be fired when tag was not added or error occured.

When error is encountered, err object is returned:

{ 
  error:true,  
  message: 'something went wrong' 
}

Example 1:

First call back is called if tags have been successfully set, second call back is called if error has occurred during tags setting:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.setTags", ["value1", "value2"], 
  function() {console.log("Tags has been set")}, 
  function(err){console.log(err.message)
}])

Example 2:

Call back is called if tags have been successfully set:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.setTags",["value1", "value2"], 
  function() {console.log("Tags has been set")
}])

Example 3:

Without call back functions:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.setTags", ["value1", "value2"]
])

segmentation.removeTag

The method deletes a provided tag that was previously set for a user with addTag, addTags or setTags. Use removeAllTags if you need to delete all user’s tags.

Parameters:

string value - set this to removeTag.
string value - tag name to be removed.
Call back - set here call back that to be fired when tag was successfully added and response from our server has been returned.
Call back - set here call back that to be fired, when tag was not added or error.

When error is encountered, err object is returned:

{ 
  error:true,  
  message: 'something went wrong' 
}

Example 1:

First call back is called if tag has been successfully removed, second call back is called if error has occurred during a tag removal:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.removeTag", "value", 
  function() {console.log("Tag has been removed")}, 
  function(err){console.log(err.message)
}])

Example 2:

Call back is called if tag has been successfully removed:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.removeTag ","value", 
  function() {console.log("Tag has been removed")
}])

Example 3:

Without call back functions:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.removeTag ", "value"
])

segmentation.removeAllTags

The method deletes all user’s tags that were previously set for a user with addTag, addTags or setTags.

Parameters:

string value - set this to removeAllTag.
Call back - set here call back to be fired, when tag was successfully added and response from our server has been returned.
Call back - set here call back to be fired, when tag was not added or error.

When error is encountered, err object is returned:

{ 
  error: true,  
  message: 'something went wrong' 
}

Example 1:

First call back is called if all tags have been successfully removed, second call back is called if error has occurred during tags removal:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.removeAllTags",  
  function() {console.log("All tags has been removed")}, 
  function(err){console.log(err.message)
}])

Example 2:

Call back is called if all tags have been successfully removed:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.removeAllTags",  
  function() {console.log("All tags has been removed")
}])

Example 3:

Without call back functions:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.removeAllTags"
])

getTags

Returns list of tag objects, associated with a subscriber.

Code:

var Gravitec = Gravitec|| [];
Gravitec.push(["getTags", callback]);

Example:

This code prints an array of the subscriber’s tags.

Gravitec.push(['getTags', function(tags) {
  var newArray = [];
  tags.map((tag)=>newArray.push(tag));
  console.log(newArray);
}])

segmentation.setAlias

Set an alias(user identifier) for subscriber to target the one.

Parameters:

string value - set this to setAlias.
string value - value to set – alias name.
Call back - set here call back to be fired, when tag was successfully added and response from our server has been returned.
Call back - set here call back to be fired, when tag was not added or error.

When error is encountered, err object is returned:

{ 
  error:true,  
  message: 'something went wrong' 
}

Example 1:

First call back is called if alias has been successfully set, second call back is called if some error has occurred during alias setting:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.setAlias", "value", 
  function() {console.log("Alias has been set")}, 
  function(err){console.log(err.message)
}])

Example 2:

Call back is called if alias has been successfully set:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.setAlias","value", 
  function() {console.log("Alias has been set")
}])

Example 3:

Without call back functions:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "segmentation.setAlias", "value" 
])

getSubscriptionData

To get visitor’s subscription detail such as subscription status, REGid, permission status and browser use this method. The method returns a subscription object in a resolved promise.

Parameters:

string value - set this to getSubscriptionData.
Call back - set here call back to be fired, when subscription data have been successfully fetched, data object contains subscription details.
Call back - set here call back to be fired, when an error occurred.

When error is encountered, err object is returned:

{ 
  error:true,  
  message: 'something went wrong' 
}

Example 1:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "getSubscriptionData", function(data) {
    console.log(data.permission); 
    console.log(data.subscription); 
    if(data.subscription) { 
      console.log(data.subscription.regID); 
    }
  }, function(err) {
    console.log(err.message);
  }
])

afterSubscription

Callback that is called after the device is successfully registered with Gravitec. Return token.

Example:

var Gravitec = Gravitec || [];
Gravitec.push(["afterSubscription", function (token) {
  console.log(token);
  //Your action
}]);

subscriptionResult

The method fires a callback after visitor interacted with subscription prompt. Visitor can press Allow, Block or just close the prompt in all these cases the method returns a relevant data.

Parameters:

string value - set this to subscriptionResult.
Call back - set here call back to be fired, when visitor press Allow, Block or closed the prompt, data object contains subscription details.
Call back - set here call back to be fired, when an error occurred.

When error is encountered, err object is returned:

{ 
error:true,  
message: 'something went wrong' 
}

Example 1:

var Gravitec = Gravitec || []; 
Gravitec.push([
  "subscriptionResult", function(data) {
    console.log(data.permission); 
    console.log(data.subscription); 
    if(data.subscription) { 
    console.log(data.subscription.regID); 
    }
  }, function(err){
    console.log(err.message);
  }
])

getSubscription

Lets you retrieve the Google Registration ID. Your handler is called after the device is successfully registered with Gravitec.

Example:

var Gravitec = Gravitec || [];
Gravitec.push(["getSubscription", function (subscriptionId) {
  if (subscriptionId) {
    console.log(subscriptionId);
  }
}]);

isSubscribed

Shows if user give permission to send notifications. Return true or false.

Example:

var Gravitec = Gravitec || [];
Gravitec.push(["isSubscribed", function (success) {
  console.log(success);
  //Your action
}]);

Generating your own Push Notification Key

STEP 1: Go to Firebase Console - https://console.firebase.google.com

1.1 Create a new project or move to a previously created project.

1.2 Go to project settings.

1.3 Select the Cloud Messaging tab

STEP 2: Generate push notification keys

2.1 At the bottom of the page, in the Web Configuration section, select "Generate key pair".

STEP 3: Save Push Notification Keys

3.1 Copy the received key and send it to the Support specialist marked as Public Key

Example: Public Key - BP7E0SP1S90AgpyBX-dTvEOfeXSSqnqLAKmHalqOrTYfIA_vK5EkEjGF0NyYUQG4Kpzs4-BVUCWXlYvEsCKyYBM

3.2 Select menu - Advanced (represented by 3 dots)

3.3 Select the menu item - "Show private key"

3.4 Copy the key you received and give it to Support specialist marked Private Key

Example: Private Key - O678UMYlpVhoaJcFLerHYc5N1g1fzffRU5poA4mhfC4I
As a result, it is necessary to pass the Public and Private Key to the Support specialist.

Example:
Public Key - BP7E0SP1S90AgpyBX-dTvEOfeXSSqnqLAKmHalqOrTYfIA_vK5EkEjGF0NyYUQG4Kpzs4-BVUCWXlYvEsCKyYBM

Private Key - O678UMYlpVhoaJcFLerHYc5N1g1fzfRU5poA4mhfC4I

Generating your own Safari Push Notification Certificate

The goals of this section are to provision your app with Apple and grant Gravitec access to manage your notifications.

1. Create Certificate Signing Request

1.1 Open Keychain Access on your Mac (it is located in Applications/Utilities) and choose the menu option Request a Certificate from a Certificate Authority….

1.2 Save Certificate

You should now see the following window (pic. 1).

Enter your email address here. Some people recommend using the same email address that you used to sign up for the iOS Developer Program, but it seems to accept any email address just fine.

Check Saved to disk and click Continue.

pic. 1

2. Create Website Push ID and apply the Certification Request to generate Certificate

2.1 Press "plus" button on the Website Push IDs.

2.2 Enter an ID, a Description and press the button Continue.

2.3 On the next pages press Register and the Done buttons.

2.4 On the Website Push IDs page select your site and press Edit.

2.5 Press Create Certificate.

2.6 Press "Choose File..", select the "certSigningRequest" file you saved in Step 1, open, and then press "Generate".

2.7 Press "Download" to save your certificate

3. Creating a p12 File

3.1 Open the website_aps_production.cer file you downloaded in the last step by double clicking on it in Finder.

3.2 After a few seconds the "Keychain Access" program should pop up. Select Login > Keys, then right click on your key in the list and select "Export"

3.3 Give name the .p12 file the same as sertificate ID (example: "web.net.0000001.gravitec"). You will have an option to protect the file with a password. Generating safari ID set the password: 1111

4. Send your p12 file to Gravitec support (support@gravitec.net)