Introduction

Welcome on the Javascript Omnisense SDK Documentation v2.0. You can use these to retrieve and add informations on your Omnisense instance.

The Javascript Omnisense SDK has 3 main purposes:

Receiving informations (ex: email, firstname, lastname, phone number, etc...)
Tracking user's actions (ex: Product view, put to cart and purchase)
Handle web push notifications subscription

Installation

<head>
  <!-- METAS -->
  <!-- CSS -->
  <!-- JS -->
  <script src="https://code.jquery.com/jquery-1.12.4.min.js"></script> <!-- Required only if you website doesn't already use it -->

  <script src="https://omnisense-common.s3.amazonaws.com/sdk/js/v2.0/omnisense.js"></script>
  <!-- /METAS -->
</head>

In order to get a Omnisense working on your website, you have to :

Add jQuery (version 1.12 or more) if your website doesn't use it
Add omnisense.js
If you want to use the webpush module, you also have to add a manifest.json file and our service worker at the root of your website (root public directory). You can download the files here.

Initialization

Basic initialization

$(document).ready(function() {
  var API_KEY = "1234567890abcdef09876543210abcde";
  var INSTANCE = "my_instance_name";

  var omnisense = new Omnisense({
    api_key: API_KEY,
    instance: IDENTIFIER
  });

  omnisense.start();
});

With Webpush module

$(document).ready(function() {
  var API_KEY = "1234567890abcdef09876543210abcde";
  var INSTANCE = "my_instance_name";
  var VAPID_PUBLIC_KEY = "BJqsb7VRCkPzeLRWWlsjXFc0xCEK_PtBJ71YKt_hK_wPuzIn_v-oFd7W5MuGzVdZ7TKjHpkvP90HiWXFSst_VUA="

  var omnisense = new Omnisense({
    api_key: API_KEY,
    instance: IDENTIFIER,
    features: ["webpush"],
    webpush: {
      vapid_public_key: VAPID_PUBLIC_KEY, //Mandatory parameter
      auto_register: true,
      prompt_message : "Pour ne rien rater de nos offres, inscrivez vous aux notifications!",
      confirm_btn: "Accepter",
      later_btn: "Plus tard",
      primary_color: "#4aacdf",
      prompt_wait_time: 7
    }
  });

  omnisense.start();
});

Once the page is fully loaded, you can initialize Omnisense. To do so, you must set your Omnisense instance identifier and API KEY, which have been provided by the Omnisense Team.

On first call of start() function, a cookie with a unique identifier is created to identify the user wheter he is connected or not.

Once the start() function has been called, you can now send user's data and actions.

The instance identifier is the first part of the URL you use to connect on omnisense. For example, if you are connected to https://my-instance.app.omnisense.io then IDENTIFIER = my-instance.

Users

Post Informations

Method name : updateUser(user: Hash, metadata: Hash)

User Registration

//Let's say the user is registering. Once he clicks the signup button, we can update his profile on Omnisense
$("#signup_btn").click(function(e) {
  e.preventDefault();
  omnisense.updateUser({
    "email": "emailaddress@provider.com",
    "first_name": "John",
    "last_name": "Doe",
    "lang": "fr",
    "country": "FR",
    "postal_code": "66000"
  });
});

User Login

// Let's say the user is logging in. Once he clicks the login button,
// we can update his profile on Omnisense
  $("#login_btn").click(function(e) {
    e.preventDefault();
    omnisense.updateUser({
      "email": "emailaddress@provider.com"
    });
  });

Metadatas

// If your want to store any other informations not matching the attributes allowed
// for the user, you have to use the metadata param. You can only store set of key/values in metadata.
$(document).ready(function() {
  // ... OMNISENSE INITIALIZATION

  omnisense.updateUser({}, {
    "purchase_count": "5"
  });
});

Method Informations

Function name: updateUser(Hash, Hash)

Method Parameters

Parameter	Value	Description
user	Hash	For the list of allowed attributes, see below.
metadata	Hash	Set of key/values to store additional informations

User Hash

Parameter	Value	Description
email	String
fb_id	String
first_name	String
last_name	String
birthday	Date
phone	String
address	String
city	String
postal_code	String
country	String	must be the iso code for country (ISO 3166)
lang	String	must be the iso code for lang (ISO 639)
sex	String	One of "male", "female"
optin	Boolean	Set to true if the user is optin to receive email
optin_sms	Boolean	Set to true if the user is optin to receive SMS
registered	Boolean	Set to true if the user has signed up to your website
custom_event_date	Date
company	String

Access to personal informations

// Example : You have a button to display personal informations page.
$("#open_personal_informations_page").click(function(e) {
  omnisense.openPersonalInformationsPage();
});

In order to let your user access and edit or delete his personal informations, you have to methods available :

omnisense.getPersonalInformationsLink() -> With this method you only get the link
omnisense.openPersonalInformationsPage() -> Directly open the page in a new tab

Tracking

User event tracking

// Let's say the user is looking a product. When the page is loaded you could
// do something like that to track your user for looking a product.
$(document).ready(function() {
  // ... OMNISENSE INITIALIZATION

  var productParameters = {
    "id": "1234",
    "name": "foo",
    "price": "25",
    "currency": "EUR",
    "media": "website"
  };

  omnisense.trackEvent("product.view", productParameters);

});

Method Informations

Function name: trackEvent(identifier: String, segments: Hash)

Method Parameters

Parameter	Value	Description
identifier	String	The action name
segments	Hash	Set of key/values describing the event

Optional Parameters

Parameter	Value	Description
callback	Callback	This callback will be fired after the action is saved

Additional settings

General

//I'm on a mobile website
omnisense.setOrigin("mobile_website");

The Javascript sdk send automatically a flag indicating the informations are tracked from "website". If you want to change this flag, you can by calling setOrigin() function. Call it before calling start() function, otherwise you could send the wrong flag to Omnisense.

Web push module

// We consider #subscribe_notification_btn is a button on your website
$("#subscribe_notification_btn").click(function(e) {
  e.preventDefault();
  omnisense.displayWebpushPrompt();
});

This module provide several parameters :

auto_register : If set to false, Omnisense will not prompt the user to subscribe to web push notifications.
prompt_message : This is the message which will appear on the prompt modal. You should use this to explain why the user should accept to subscribe to your notifications.
confirm_btn : Button which will trigger the native permission request. Should be something like "Accept" or "Allow".
later_btn : Button which will dismiss the modal. Shoud be something like "Later".
primary_color : Color of the modal, in hexa.
prompt_wait_time : When the user clicks "later", the prompt modal won't be displayed until prompt_wait_time days.

If you want to handle the registration manually, you can call the displayWebpushPrompt() function anywhere you want.