FAQ

Frequently asked questions

1. How can I configure push notifications on my site?

Add your site to the control panel and choose the platform "For website" -> "Chrome". Then follow the instructions that are given during the registration process. instructions for setting up Gravitec Web Push on your site can also be rather helpful.

2. How to set up push notifications in the mobile application on Android?

Create new "app" and choose the platform "For mobile App" -> "Android". Then follow the instructions.

3. I want to send push notifications to users that visit my site using mobile devices. What platform do I need to choose: "Android" or "Chrome"?

Choose Gravitec for Chrome. In this case push notifications will be delivered to Google Chrome browser both on desktop computers, and on mobile devices powered by Android.

Note: You should choose Push for Android App only if you want to use push notifications in your mobile application.

4. I already use push notifications from Gravitec on the one of my websites. How can I register another one in the control panel?

Open control panel, find and click "App list", in the left top corner of the screen, then choose "Create app" in that list. After that, choose "For website" -> "Chrome" and follow the instructions that are given during the installation process.

5. I activated my site in Gravitec, made some changes and the integration disappeared after that. How can I get the code for installing push notifications on my site again?

Open the "App list" menu, choose your site and find the "Installation" page. You can copy the code for integrating Gravitec with your site from here.

6. I’ve created a Gravitec account and added integration code to my website. How can I collect subscribers on my HTTPS-based website?

Your users can subscribe via the standard Chrome dialog box. Code for calling this dialog box can be found on the "Installation" page of control panel (located in "site management" section).

Alternatively, you can offer subscription on performing certain user actions on site.

Documentation for developers: https://docs.gravitec.net/hc/ru/articles/208904085-Website-SDK-HTTPS-Installation

Note: Regardless of the format, only visitors using Google Chrome browsers can subscribe to push notifications.

7. I've created a Gravitec account and added integration code to my website. How can I collect subscribers on my HTTP-based website?

You can use the standard Gravitec widget.

Choosing widget colors, changing widget text and getting integration code can be done on "Installation" page of control panel (click "App list" menu and choose your site).

Alternatively, you can offer subscription on performing certain user actions on site.

Documentation for developers: https://docs.gravitec.net/hc/ru/articles/208244269-Website-SDK-HTTP-Installation

Note: Regardless of the format, offer to subscribe to push notifications will be shown only to visitors that use Google Chrome browser.

8. Can I send push notifications directly from my website instead of using the control panel?

Yes, it’s possible to send push notifications from your own server using our API. Here is the documentation for developers: https://docs.gravitec.net/hc/ru/articles/208958345-Send-Push-Notification

9. How can I send personal notifications to individual subscribers?

Give unique names (aliases) to your subscribers. Usernames, phone numbers or emails can be used for this purpose.

Send unique messages to unique users using their aliases. Use our API for setting aliases for users. Here is the documentation for developers: https://docs.gravitec.net/hc/ru/articles/208958285-Website-SDK-API

  10. How can I group and target certain subscribers?

You can create subscriber groups using special tags. Use these tags for segmenting and grouping your subscribers. You can use as many tags as you want. Use our API for setting tags for users. Here is the documentation for developers: https://docs.gravitec.net/hc/ru/articles/208958285-Website-SDK-API

  11. I have more questions. Where can I get answers?

Feel free to ask us: support@gravitec.net

We will surely help you with your issue!

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.

 

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:

doc-01.png

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>
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.name));
  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);
  }
]) 

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 GCM Push Notification Key

STEP 1: Create a Google Project and save the "Project Number"

1.1 Create a project at https://console.developers.google.com/project for your app.

doc-02.png

1.2 Select your Project and go to IAM & admin->Settings. Your project number should be located on this page.

Copy the "Project Number" from this page.

You will need to add it to the source code of your app later when you follow the SDK guide.

doc-03.png
STEP 2: Turn on "Google Cloud Messaging" API

2.1 Under APIs & Services>Library, search for "Google Cloud Messaging". Turn it on.

doc-04.png
STEP 3: Create and save Server Key

3.1 Under "APIs & services" > "Credentials", click "Create credentials".

 

3.2 Select "API key"

doc-05.png

3.3 Press the "Create" button.

IMPORTANT

DO NOT enter anything into the box.

 

3.4 Go to https://console.firebase.google.com and import your google project

doc-06.png

3.5 Click to "Project overview settings" and choose "CLOUD MESSAGING" tab. Copy Server Key.

doc-07.png
STEP 4: Send your GCM credentials to Gravitec support

4.1 Send your Project Number(Sender ID) and GCM Server key to support@gravitec.net.

 

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….

doc-08.png

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.

doc-09.png

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.

doc-10.png

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

doc-11.jpg

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.

doc-12.png

2.5 Press Create Certificate.

doc-13.png

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

doc-14.png

2.7 Press "Download" to save your certificate

doc-15.png
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.

doc-16.png

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"

doc-17.png

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)

 

Server API

Server API Overview

About API

Our API is a REST API, which supports HTTP error codes to indicate API errors and use basic HTTP authentication to authenticate user’s account. All requests body must be in JSON format, we do not support other formats. However, we’re open-minded team and we are opened for any suggestions on formats or API logic. Please, write us support@gravitec.net if you have got any suggestions or issues with the API.

In addition to the REST API we provide to our clients WEB SDK API, which is essentially a JavaScript API designed to manage your subscriber’s database. For example, this SDK provides functions for tagging and setting aliases to your subscribers. Those tags and aliases could be useful for marketing purposes, such as – segmentation of subscribers’ database by their behavior or by their preferences.

Authentication

Authenticate your account when using the API by including your APP KEY and APP SECRET keys in the request. You can find your APP keys in the Site Settings page.

Your APP key allows to send push messages to all your subscribers database, so be careful and keep them in secret!

Authentication to the APP is performed via HTTP Basic Auth:

  • Provide your application key ("APP_KEY") as the basic AUTH username value
  • Provide your application secret ("APP_SECRET") as the basic AUTH password value
  • All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Code example:

// via shell
// example APP_KEY = 1e26f7bb3f81e1ab789d3e20b9cf6325
// example APP_SECRET = 9bb59fcbff38b85647c421c65cca06ce
curl -X \
  -u "1e26f7bb3f81e1ab789d3e20b9cf6325:9bb59fcbff38b85647c421c65cca06ce" \
  -H "Content-Type: application/json" \
  https://uapi.gravitec.net/api/v2/push.json

// or
curl -X \
  -u "1e26f7bb3f81e1ab789d3e20b9cf6325:9bb59fcbff38b85647c421c65cca06ce" \
  -H "Content-Type: application/json" \
  https://uapi.gravitec.net/api/v2/push.json

Send Push Notification V2

Definition

Method: POST

Endpoint: https://uapi.gravitec.net/api/v2/push.json

Headers: Content-Type: application/json

Request body:

{
 "send_date": "now",
 "message": "Push message text",
 "ttl": 3600,
 "chrome": {
   "header": "CHROME TITLE",
   "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
   "redirect_url": "http://yoursite.com"
 },
 "audience": {
   "all": 1
 }
}
Arguments

send_date

Optional

default: "now"

type: String or Int

Date and time, when you want your push to be sent. For delayed push, you must set the desired date and time, which have to be in the future and for immediate sending set it to “now”.

NOTE: Time must be in UNIX_TIME format, which is essentially the number of seconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, minus the number of leap seconds that have taken place since then

Example:

"send_date": "now"   - immediate sending
"send_date": 1509058800 – send push at 2017.Oct.26 23:00:00

message

Required

type: String

Text, which will be displayed as push message text (pic. 2).

NOTE: Maximum length of the message is 240 symbols.

Example:

"send_date": "now"   - immediate sending
"send_date": 1509058800 – send push at 2017.Oct.26 23:00:00
doc-18.png

pic. 2

ttl

Optional

default: 3600

type: Int

The number of seconds that a message may be stored if the user is not immediately available.

NOTE: The number must be in between 0 and 2 419 200

NOTE: Keep in mind that a TTL value of 0 means messages that can't be delivered immediately to users are discarded. However, because such messages are never stored, this provides the best latency for sending notification messages

Example:

"ttl ": 14400   - time-to-live is set to 4 hours

chrome

Required

The “Chrome” section is required some arguments within the section are not required.

 

header

Optional

default: Title

type: String

Title or header of the message.

NOTE: Max length of header is 65 symbols

Example:

"header": "Just another header"

Chrome:

doc-19.png

Firefox:

doc-20.png

icon

Required

type: String

URL of the notification's icon. Sets the notification icon to specified image URL. Image must be at least 80x80 pixels and with 1:1 ratio. The pictures without that ratio will be resized and probably distorted.

NOTE: Provide correct URL, without spaces or tabs at the start and at the end of the URL and with ending .jpg, .jpeg or .png, otherwise the error will be fired.

NOTE: Maximum length of the URL is 1000 symbols.

NOTE: Providing “icon": “” will set the icon to default site icon, which can be set in the Site Settings page.

Example:

"icon": "https://push.gravitec.net/img/gravitecBig.jpg
doc-21.png

redirect_url

Required

type: String

URL, which will be opened in user’s browser if user clicks on the notification.

NOTE: Maximum length of the URL is 1000 symbols.

NOTE: Provide correct URL, without spaces or tabs at the start and at the end of the URL, otherwise the error will be fired.

Example:

"redirect_url": "http://yoursite.com/news"

audience

Required

The “Audience” section is required. The section must contain only one of these variables: alltokensaliases or tags.

 

all

Optional

type: Int

Setting this parameter in any value means that message will be send to all subscribers.

NOTE: Any JSON correct value is accepted, but we would recommend you to set it in 1, as mentioned in example.

Example (of the whole Audience section):

"audience": {
  "all": 1
}

tokens

Optional

type: Array

Specifying a list of subscribers’ IDs in this parameter means that message will be send exactly to the list of subscribers specified. You can get subscriber’s ID by using getSubscription function from our Web SDK API

NOTE: Array size is limited to 100 IDs.

Example:

"tokens": ["dec301908b9ba...8df85e57a58e40f96f", "523f4c2068674f1fe...2ba25cdc250a2a41"]

aliases

Optional

type: Array

Specifying a list of aliases means that message will be sent exactly to the list of subscribers who are associated with aliases provided in the list. You can set an alias by using setAlias function from our Web SDK API.

Example:

"aliases": ["own_id_device_1", "own_id_device_2", "own_id_device_3"]

tags

Optional

type: Array

Specifying a list of tags means that message will be send exactly to the list of subscribers who were tagged with tags provided in the list. You can tag your subscribers by using addTag or setTags function from our Web SDK API

Example:

"tags": ["tag1", "tag2", "tag3"]
Examples

Send push to all followers of site

curl -X POST \
-H "Content-Type: application/json" \
-u "APP_KEY:APP_SECRET" \
--data '{
  "message": "Push message",
  "chrome": {
    header": "title message",
    icon": "http://example.com/icon.png",
    redirect_url": "http://yoursite.com/new"
  },
  "audience": {
    "all": 1
  }
}' \
https://uapi.gravitec.net/api/v2/push.json

Send push to followers of site who were tagged with tag1 and tag2

curl -X POST \
-H "Content-Type: application/json" \
-u "APP_KEY:APP_SECRET" \
--data '{
  "message": "Push message",
  "chrome": {
    "header": "title message",
    "icon": "http://example.com/icon.png",
    "redirect_url": "http://yoursite.com/new"
  },
  "audience": {
    "tags": ["tag1", "tag2"]
  }
}' \
https://uapi.gravitec.net/api/v2/push.json
Responses (Results and Errors)

200 OK - Standard response for successful HTTP requests

Request

{
  "send_date":"now",
  "message":"Push message text",
  "ttl":3600,
  "chrome": {
    "header":"CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  },
  "audience": {
    "all": 1
  }
}

Response

{
  "id": "1578964386674900992",
  "status": "completed",
  "message": "Push message text",
  "title": "CHROME TITLE",
  "platforms": "chrome",
  "ttl": "3600",
  "date": "Tue Sep 19 13:43:02 EEST 2017"
}

403 FORBIDDEN - authorization failed

Request

POST /api/v2/push.json HTTP/1.1

Host: api.gravitec.net

Content-Type: application/json

Authorization: Basic NTQ1OTA1OTA1OTQwNTk0MGdwZ2tqOmVyZmdkZmdkZmdkZmc=

Cache-Control: no-cache

{
  "send_date": "now",
  "message": "Push message text",
  "ttl": 3600,
  "chrome": {
    "header": "CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  },
  "audience": {
    "tags": ["tag1", "tag2", "tag3"]
  }
}

Response

{
  "status": "incomplete by bad auth",
  "error_message": "There is no web site with appKey: 5459059059405940gpgkj"
}

404 NOT FOUND - missed required parameter

Request

{
  "send_date": "now",
  "message": "Push message text",
  "ttl": 3600,
  "chrome": {
    "header": "CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  }
}

Response

{
 "status": "incomplete by missed req param(s)",
 "error_message": "Audience required"
}

412 PRECONDITION_FAILED - bad message

Request

{
  "message": "Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test message$Test Test message$Test message$Test message$Test message$Test message$Test test",
  "chrome": {
   "header": "Test it out!",
   "icon": "https://cdn.gravitec.net/img/logo_footer.png",
   "redirect_url": "https://gravitec.net/"
   "all": 1
  },
  "send_date": "now"
}

Response

{
 "status": "incomplete by wrong param(s)",
 "error_message": "message max length is 1000 symbol"
}

417 EXPECTATION_FAILED - wrong parameter

Request

{
  "send_date": "2017-09-20",
  "message": "Push message text",
  "ttl":3600,
  "chrome": {
    "header": "CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  },
  "audience": {
    "all": 1
  }
}

Response

{
  "status": "incomplete by wrong param(s)",
  "error_message": "date must be timestamp or now"
}

424 FAILED_DEPENDENCY - bad audience

Request

{
  "send_date": "now",
  "message": "Push message text",
  "ttl": 3600,
  "chrome": {
    "header":"CHROME TITLE",
    "icon": "https://push.gravitec.net/img/gravitecBig.jpg",
    "redirect_url": "http://yoursite.coma"
  },
  "audience": {
    "tags": ["tag1", "tag2", "tag3"]
  }
}

Response

{
  "status": "incomplete by bad audience",
  "error_message": "tags list is invalid"
}

Send Push Notification V3

Set alias for subscriber V3

Definition

Method: POST

Endpoint: https://uapi.gravitec.net/api/v3/alias

Request parameters:

  • regId - subscriber’s token [Required, 1-255 symbols string]
  • name - desired alias name [Required, 1-255 symbols string]

NOTE: All request parameters names and values are case-sensitive.

Request URL example:

https://uapi.gravitec.net/api/v3/alias?regId=someregid&name=newalias
Responses

200 OK

The alias was successfully added

400 Required String parameter "name" is not present

"name" parameter was not provided in request

400 Required String parameter "regId" is not present

"regId" parameter was not provided in request

422 Unprocessable Entity

No follower with regID provided was found

Body:

{
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "error": "Incomplete by wrong param(s)!",
  "errorDescription": "There is no follower with this regId!"
}

422 Unprocessable Entity

Provided alias name length was more than 255 symbols

Body:

{
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "error": "Incomplete by wrong param(s)!",
  "errorDescription": "Max alias length is 255!"
}


Set Tag for subscriber V3

Definition

Method: POST

Endpoint: https://uapi.gravitec.net/api/v3/tag

Request parameters:

  • regId - subscriber’s token [Required, 1-255 symbols string]
  • name - desired tag name [Required, 1-255 symbols string]

NOTE: All request parameters names and values are case-sensitive.

NOTE: Tags saving method behaves with case sensitive values like:

First tag will be saved in exact case it provided, if another tag, which in case-insensitive comparison is the same one, provided, it will not be added as a new tag – the system considers it as the same as previous.

Request URL example:

https://uapi.gravitec.net/api/v3/tag?regId=someregid&name=tagname
Responses

200 OK

Tag was successfully added

400 Required String parameter "name" is not present

"name" parameter was not provided in request

400 Required String parameter "regId" is not present

"regId" parameter was not provided in request

422 Unprocessable Entity

No follower with regID provided was found

Body:

{
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "error": "Incomplete by wrong param(s)!",
  "errorDescription": "There is no follower with this regId!"
}

422 Unprocessable Entity

Provided tag name length was more than 255 symbols

Body:

{
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "error": "Incomplete by wrong param(s)!",
  "errorDescription": "Max alias length is 255!"
}

Delete subscriber’s tag V3

Definition

Method: DELETE

Endpoint: https://uapi.gravitec.net/api/v3/tag

Request parameters:

  • regId - subscriber’s token [Required, 1-255 symbols string]
  • name - desired tag name [Required, 1-255 symbols string]

NOTE: All request parameters names and values are case-sensitive.

Request URL example:

https://uapi.gravitec.net/api/v3/tag?regId=someregid&name=tagname
Responses

200 OK

Tag was successfully deleted

400 Required String parameter "name" is not present

"name" parameter was not provided in request

400 Required String parameter "regId" is not present

"regId" parameter was not provided in request

422 Unprocessable Entity

No follower with regID provided was found

Body:

{
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "error": "Incomplete by wrong param(s)!",
  "errorDescription": "There is no follower with this regId!"
}

422 Unprocessable Entity

Provided tag was not found for the subscriber with provided regId.

Body:

{
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "error": "Incomplete by wrong param(s)!",
  "errorDescription": "The follower doesn't have this tag!"
}

422 Unprocessable Entity

Provided tag name length was more than 255 symbols

Body:

{
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "error": "Incomplete by wrong param(s)!",
  "errorDescription": "Max alias length is 255!"
}

Get subscriber’s alias V3

Definition

Method: GET

Endpoint: https://uapi.gravitec.net/api/v3/alias

Request parameters:

  • regId - subscriber’s token [Required, 1-255 symbols string]

NOTE: All request parameters names and values are case-sensitive.

Request URL example:

https://uapi.gravitec.net/api/v3/alias?regId=someregid
Responses

regIdExists [boolean]

  • Is "true" if provided in request regId is an actual subscriber’s token
  • Set in "false" if provided in request regId does not exists as actual subscriber’s token

aliasExists [boolean]

  • Is "true" if provided in request regId is an actual subscriber’s token and there is an active alias for that token
  • Is "false" if provided in request regId is an actual subscriber’s token and there is no active alias for that regID
  • Does not present in response if regIdExists is "false"

isActiveFollower [boolean]

  • Is "true" if provided in request regId is a token of an active subscriber
  • Is "false" if provided in request regId is a token of an inactive subscriber
  • Does not present in response if regIdExists is "false"

alias [string]

  • Is an actual and active alias for provided in request regId
  • Does not present in response if regIdExists is "false"

200 - OK

400 - Required String parameter regId is not present

 
Examples

RegId property was not in request

Request:

https://uapi.gravitec.net/api/v3/alias?regId=

Response code:

400 - Required String parameter regId is not present

RegId exists as actual subscriber’s token

Request:

https://uapi.gravitec.net/api/v3/alias?regId=okf8kj589ktGF5g3gF#gf3#46g^^6gfGfgfgfg%g5g

Response code:

200 - OK

Response body:

{
  "regIdExists": "false"
}

There is no active alias for regID

Request:

https://uapi.gravitec.net/api/v3/alias?regId=okf8kj589ktGF5g3gF#gf3#46g^^6gfGfgfgfg%g5g

Response code:

200 - OK

Response body:

{
  "regIdExists": "true",
  "aliasExists": "false",
  "isActiveFollower": "true"
}

There is an active alias for regID and subscriber is not in an active state

Request:

https://uapi.gravitec.net/api/v3/alias?regId=okf8kj589ktGF5g3gF#gf3#46g^^6gfGfgfgfg%g5g

Response code:

200 - OK

Response body:

{
  "regIdExists": "true",
  "aliasExists": "true",
  "isActiveFollower": "false",
  "alias": "alias1"
}

There is an active alias for regID and subscriber is in an active state

Request:

https://uapi.gravitec.net/api/v3/alias?regId=okf8kj589ktGF5g3gF#gf3#46g^^6gfGfgfgfg%g5g

Response code:

200 - OK

Response body:

{
  "regIdExists": "true",
  "aliasExists": "true",
  "isActiveFollower": "true",
  "alias": "alias1"
}
Send Push Notification V3

Definition

Method: POST

Endpoint: https://uapi.gravitec.net/api/v3/push

Headers: Content-Type: application/json

Request body properties:

{
  "send_date":"",
  "ttl":"",
  "display_time": "",
	"is_transactional":"",
  "payload": {
    "message":"",
    "title":"",
    "icon":"",
    "image":"",
    "redirect_url":"",
    "buttons": [{
      "title":"",
      "url":""
    }]
  },
  "audience": {
    "tokens":[""],
    "aliases":[""],
    "tags":[""]
  }
}
Properties

send_date

Optional

default: ""

type: String or Int

Date and time, when you want your push to be sent. For delayed push, you must set the desired date and time, which have to be in the future and for immediate sending set it to "now".

NOTE: Time must be in UNIX_TIME format, which is essentially the number of milliseconds that have elapsed since 00:00:00 Coordinated Universal Time (UTC), Thursday, 1 January 1970, minus the number of leap milliseconds that have taken place since then

Example:

"send_date": "" - immediate sending
"send_date": 1509058800000 – send push at 2017.Oct.26 23:00:00

ttl

Optional

default: 28800

type: Int

The number of seconds that a message may be stored if the user is not immediately available.

NOTE: The number must be in between 0 and 2 419 200

NOTE: Keep in mind that a TTL value of 0 means messages that can't be delivered immediately to users are discarded. However, because such messages are never stored, this provides the best latency for sending notification messages

Example:

"ttl ": 28800   - time-to-live is set to 8 hours

display_time

Optional

default: 60

type: Int

The number of seconds that a message will be displayed on participant’s screen

NOTE: If set in 0 – the message will be displayed until user clicks on it

NOTE: Maximum time is 2419200

 

is_transactional

Optional

default: false

type: boolean

Marks a push message as Transactional, thus the message will not be displayed in the main campaign history section of the web application (https://push.gravitec.net). Use this if you send a great deal of small messages, which are by itself contains transactional data like personal notifications for your users, reminders, etc.

NOTE: If omitted, false" value will be set for a push message

 

payload

Required

The "Payload" section is required, whereas some arguments within the section are not required.

 

message

Required

type: String

Text, which will be displayed as push message text

NOTE: Maximum length of the message is 1000 symbols.

Example:

"message": "Push message text"
doc-18.png

title

Optional

default: Title

type: String

Title or header of the message.

NOTE: Max length of title is 1000 symbols.

Example:

"header ": "Just another header"

Chrome:

doc-19.png

Firefox:

doc-20.png

icon

Required

type: String

URL of notification's icon. Sets the notification icon to specified image URL. Image must be at least 80x80 pixels and with 1:1 ratio. Pictures without that ratio will be resized with its aspect ratio and put on a white square.

NOTE: Provide correct URL, without spaces or tabs at the start and at the end of the URL and with ending .jpg, .jpeg or .png, otherwise the error will be fired.

NOTE: Maximum length of the URL is 1000 symbols.

NOTE: Providing "icon": "" will set the icon to default site icon, which can be set in the Site Settings page

Example:

"icon": "https://push.gravitec.net/img/gravitecBig.jpg"

1:1 aspect ratio and more than 80x80 on X and Y sides:

doc-21.png

1:1.2 aspect ratio and more than 80 on Y side:

doc-22.png

1.2:1 aspect ratio and more than 80 on X side:

doc-23.png

Less than 80x80 on X and Y sides:

doc-24.png

image

Optional

type: String

URL of big picture to display below the notification main body. For the best results provided image must be with 1.5:1 sides ratio and size at least 360x240 pixels.

NOTE: Provide correct URL, without spaces or tabs at the start and at the end of the URL and with ending .jpg, .jpeg or .png, otherwise the error will be fired

NOTE: Maximum length of the URL is 1000 symbols.

NOTE: Pictures, which are not in 1.5:1 ratio or less then 360x240 and will be resized according to their aspect ratio and put on top of a white image of 360x240 px

Different image processing examples:

1.5:1 aspect ratio and more or equal than 360x240 on X and Y sides accordingly:

doc-25.png

1:1.2 aspect ratio and more than 240 on Y side:

doc-26.png

1.2:1 aspect ratio and more than 360 on X side:

doc-27.png

Less than 360x240 on X and Y sides:

doc-28.png

redirect_url

Required

type: String

URL which will be opened in user’s browser if user clicks on the notification.

NOTE: Maximum length of the URL is 1000 symbols.

NOTE: Provide correct URL, without spaces or tabs at the start and at the end of the URL, otherwise the error will be fired.

Example:

"redirect_url": "http://yoursite.com/news"

buttons

Optional

Specify in this array one or two action buttons, which will be displayed below the notification main body:

Example:

doc-29.pngdoc-30.png

title

Required

type: String

Provide appropriate title for the button.

NOTE: Max length of title is 48 symbols

 

url

Required

type: String

URL which will be opened in user’s browser if user clicks on the notification.

NOTE: Maximum length of the URL is 1000 symbols.

NOTE: Provide correct URL, without spaces or tabs at the start and at the end of the URL (rfc3986)

 

audience

Optional

The "Audience" section is optional.

NOTE: If omitted, the system shall send push message to all subscribers.

NOTE: If set - the section must contain only one of these variables (in other case, error will be fired):

 

tokens

Optional

type: Array

Specifying a list of subscribers’ IDs in this parameter means that message will be send exactly to the list of subscribers specified. You can get subscriber’s ID by using getSubscription function from our Web SDK API.

NOTE: Array size is limited to 100 IDs.

Example:

"tokens": ["dec301908b9ba...8df85e57a58e40f96f", "523f4c2068674f1fe...2ba25cdc250a2a41"]

aliases

Optional

type: Array

Specifying a list of aliases means that message will be sent exactly to the list of subscribers who are associated with aliases provided in the list. You can set an alias by using setAlias function from our Web SDK API.

Example:

"aliases": ["own_id_device_1", "own_id_device_2", "own_id_device_3"]

tags

Optional

type: Array

Specifying a list of tags means that message will be send exactly to the list of subscribers who were tagged with tags provided in the list. You can tag your subscribers by using addTag or setTags function from our Web SDK API.

Example:

"tags": ["tag1", "tag2", "tag3"]
Responses (Results and Errors)

200 OK - Standard response for successful HTTP requests

Request

{
  "payload": {
    "message": " Test massage",
    "title": "Test message",
    "redirect_url": "https://gravitec.net"
  }
}

Response

{
  "id": "1590394828308348928",
  "send_date": "1516718700678",
  "ttl": 86400,
  "display_time": 60,
  "payload": {
    "title": "Test message"
  }
}

403 FORBIDDEN - authorization failed

Request

POST /api/v3/push HTTP/1.1
Host: api.gravitec.net
Content-Type: application/json
Authorization: Basic Z2hqZ2hqZ2g6aGdtamdoag==
Cache-Control: no-cache

{
  "payload": {
    "message": "Test massage",
    "title": "Test message",
    "redirect_url": "https://gravitec.net"
  }
}

Response

{
  "status": "incomplete by bad auth",
  "error_message": "There is no web site with appKey: 5459059059405940gpgkj"
}
Get push Notification stats

Definition

Method: GET

Endpoint: https://uapi.gravitec.net/api/v3/messages/

Request parameters:

  • campaignID - Campaign ID [Required, Id from “Send Push Notification V3]

NOTE: All request parameters names and values are case-sensitive.

Request URL example:

https://uapi.gravitec.net/api/v3/messages/1603861504654835713
Responses

200 OK

The alias was successfully added

400 Required parameter "campaignID" is not present

"campaignID" parameter was not provided in request

422 Unprocessable Entity

No Push Campaign with campaignID provided was found

Body:

{
"httpStatus": "UNPROCESSABLE_ENTITY", 
"error": "Incomplete by wrong param(s)!", 
"errorDescription": "There is no message with this id!"
}