How to integrate Receptive with your product

Why do I need to set up the Receptive integration?

It's pretty simple to install Receptive in your SaaS app.

In summary, you paste some static javascript into your web app, and create a user-specific snippet of data that will be sent to Receptive’s servers.

• Step 1: Install Receptive
• Step 2: Check your installation
• Step 3: Let your customers log in (via portal or widget)

Step 1: Install Receptive

First, you need to choose whether you're doing a basic or secure install. A basic install uses the receptive integration without JWT, while the secure install uses JWT with a shared secret.

Basic Install

Declare a JavaScript var called 'receptiveAppSettings' just before the closing body tag. The object below contains data about you and your customer:

<script>
  var receptiveAppSettings = {
    "return_url":"http://example.com/user/123",
    "account":{
      "id":"321",
      "name":"Company Ltd",
      "monthly_value":"99.99",
      "is_paying":"true"},
    "vendor":{
      "id":"XXXX"},
    "user":{
      "email":"joe@example.com",
      "id":"123",
      "full_name":"Joe Bloggs",
      "allowed_products":[{"name": 'MyProduct', "id": 'my_product_external_id'}]
    }
  };
</script>

You'll need to generate at least some of this data on the server side. You can see which data you can put in the snippet here.

To embed the Receptive integration, you need to paste the following JavaScript code before the closing body tag of your app, and after the 'receptiveAppSettings' var you built previously:

<script>
  (function() {
    function async_load() {
      var s = document.createElement('script');
      s.type = 'text/javascript'; s.async = true;
      s.src = 'https://receptive.io/js/widget/widget.js';
      var x = document.getElementsByTagName('script')[0];
      x.parentNode.insertBefore(s, x);
    }
    if (window.attachEvent) {
      window.attachEvent('onload', async_load);
    } else {
      window.addEventListener('load', async_load, false);
    }
  })();
</script>

Secure Install

You can find a list of libraries to generate JWT tokens for various languages here.

Secure mode requires requests to be signed using your shared secret with JWT. The following example code can sign requests on your server and render the Receptive integration:

const jwt  = require('jsonwebtoken'); // Using node-jsonwebtoken library

var user = {uid: 'a123456', isPaying: 'true'...}; // User data from your app

var snippet = { # An object representing the widget settings for the current user
  account: {
    id: user.account.uid,
    is_paying: user.account.is_paying,
    monthly_value: user.account.value
  },
  vendor: {
    id: "XXXXX" // This is your Receptive public id
  },
  user: {
    full_name: user.full_name,
    email: user.email,
    id: user.uid
  },
  return_url: "http://example.com"
};

var jwt_token = jwt.sign(snippet, "XXXXX", {algorithm: "HS256"}); // A JWT token created using your shared secret

JSON.stringify({ // The encoded token should be passed to the frontend as a javascript object
  jwt: jwt_token
});

The public vendor ID and the shared secret (denoted by XXXXX in the above code) can be found by logging in to Receptive and heading to Settings > Install Receptive.

At least some of this code will have to be generated server-side. You can see which data you can put in the snippet here.

Then you need to pass the snippet to the frontend and use it to declare a JavaScript var called 'receptiveAppSettings' just before the closing body tag.

To embed Receptive you need to paste the following JavaScript code before the closing body tag of your app, and after the 'receptiveAppSettings' var:

<script>
  (function() {
    function async_load() {
      var s = document.createElement('script');
      s.type = 'text/javascript'; s.async = true;
      s.src = 'https://receptive.io/js/widget/widget.js';
      var x = document.getElementsByTagName('script')[0];
      x.parentNode.insertBefore(s, x);
    }
    if (window.attachEvent) {
      window.attachEvent('onload', async_load);
    } else {
      window.addEventListener('load', async_load, false);
    }
  })();
</script>

Once Receptive is installed, your customers can access Receptive, create suggestions and see your roadmap. The best thing is you don’t have to set up and manage logins and passwords for your customers, the Receptive integration automates that.

Rails: Rails example on GitHub.

Angular and other single-page javascript apps work great, but you may need to take an extra step after your user logs in. 

Step 2: Check your installation

Log in to your app, and using Chrome development tools or similar, look for a POST to http://api.eu-west-1.receptive.io/widget/ping. You should see a 200 OK response with a body containing {message:received}. If there are any problems with your snippet you’ll see an error message in the response.

Use the API Console to see what Receptive is receiving from your integration pings - this link API Console: Last 10 Pings. will show you the last 10 pings we’ve received on your account. Check the “data” field looks how you expect it to, i.e. no missing fields etc.

Step 3: Let your customers log in (via portal or widget)

There are two options for letting your customers login to Receptive.

1. Widget view

The embedded widget can be turned on in one click. Just go to "Settings" from the drop down menu, click "Customer view" and select "Widget view". 

By default you'll get a tab on the right-hand side of your app, saying "Suggest a Feature". See the following example install:

Below you will be able to change the location, color, and wording of the toggle / button. 

You can also use your own link / button to open the widget by selecting the option under "Custom toggle":

Click "Save" to enable your updates. 

Read more about the widget view here.

2. Portal view (default)

To use the portal view, you need to add a link, button, etc in your app so customers can click to access Receptive. See examples here.

To load Receptive on the current page, simply use the following:

<a href="#" onclick="receptivePublicLib.loginAndRedirect()">Suggest Features</a>

or to load Receptive in a new tab, use the following:

<a href="#" target="_blank" onclick="receptivePublicLib.loginAndRedirect({anchor: this}); return false;">Suggest Features</a>

Related:

See our security details here.