How to integrate Receptive with your app

anim2.gif

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 a javascript widget into your web app, and create a snippet of data that the widget will send to Receptive’s servers.

Once the widget is installed, your customers can access Receptive, create feature 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 widget automates that.

Groovy: Groovy widget signing library on GitHub

Python: pip install receptive Python library on GitHub

Rails: Rails example on GitHub.

Step 1: Build your snippet

This is just a javascript object containing data about you and your customer. Declare a JavaScript var called receptiveAppSettings just before the closing <body> tag.

You’ll need to generate at least some of this data on the server side. See the details below of the data you can put into the snippet, or download a CSV here.

  • User is the end user of your app, an individual
  • Account is a group of end users, usually a company
  • Vendor is you, the SaaS vendor

Only render your Receptive widget on pages visible only to your signed-in customers.

View / download this data as a google doc

Key Required? Description Example
account.created_at Optional When the account was created. Dates should be serialised in the formyyyy-MM-ddTHH:mm:ss.SSSZ "2014-04-01T12:34:56.789Z"
account.id Required Your unique identifier for the account. "123456"
account.is_paying Required We use this to differentiate between paying customers & free triallers. Should be the string "true" or "false" (in double quotes). "true"
account.monthly_value Optional The monthly value of the account to you. We use this to help prioritise feature requests. Usually, but not always, a financial value, but feel free to use your own definition of value. Should be a number formatted to two decimal places. "99.99"
account.name Optional The account name, usually a company name "Apple Inc."
user.created_at Optional When the end user was created. Dates should be serialised in the formyyyy-MM-ddTHH:mm:ss.SSSZ "2014-04-01T12:34:56.789Z"
user.email Required The end user's email "joe@your-customer.com"
user.full_name Required The end user's name "Joe Smith"
user.id Required Your unique identifier for the end user. Usually not equal to the account.id, unless all your customers are individuals. "4564573"
vendor.id Required Our identifier for you, the SaaS vendor. Get this from the integrate page. "9ec411e2...."
return_url Optional The account return URL. We link to this URL to let your customer return from Receptive to your app. This may be different for each of your customer accounts "http://example.com/345"
user.allowed_products Sometimes required* if using multi-products  

Products that user is permitted to view

*By default your customer users will only have access to the first (default) product in your account.

 [{"name" => 'Receptive', "id" => 'external_id'}, {"name" => 'Product A', "id" => 'Product A'}]

Where external_id is the existing or new product identifier. Read more here.

 
account.tags Optional Account tag categories and their associated tags Simple: ["automotive", "london"]
Tags in categories: [{"location":["london","paris"]}, {"industry":["automotive"]}]
Mixed simple and categories: "["automotive", {"location":["london","paris"]}]
user.tags
Optional User tag categories and their associated tags Simple: ["sales", "london"]
Tags in categories: [{"location":["london","paris"]}]
Mixed simple and categories: "["sales", {"location":["london","paris"]}]
feature.tags Optional Tags automatically set on features created by the user specified in this snippet Simple: ["beta", "london"]
Tags in categories: [{"area":["sales","stock"]}]
Mixed simple and categories: "["beta", {"area":["sales","stock"]}]

View / download this data as a google doc

Step 2: How to sign your snippet (required only for secure mode)

Receptive’s javascript widget will post snippet data to the Receptive API via AJAX. The possibility that users can tamper with their data before it is sent to your Receptive account can be eliminated by using Secure Mode. If you have very rigorous data security requirements you might want to consider using Secure mode.

We recommend that you switch secure mode ON, but you might want to try Receptive out without doing any server-side development — in that case, switch secure mode off. You can choose secure mode on the integrate page

Secure mode requires you to sign the data sent to Receptive using a secret shared between your server and our server.

If you switch secure mode off, the data sent will always be processed. With secure mode on, Receptive will ignore pings and login attempts from the widget if a correctly signed payload has not been received. Any attempt by the end-user to tamper with the payload will then be detected by the Receptive API and the data dropped.

We use the well known JWT (JSON Web Token) standard to sign and validate the payload. There are many libraries provided for free that will do the majority of the work for you. This link provides additional links to libraries for all main languages.

Generating a JSON Web Token (JWT) and updating your snippet

On your server you will need to:

  1. Take the data in the snippet
  2. Generate a JSON Web Token using the 'HS256' algorithm
  3. Replace the snippet in the browser so it includes a new "jwt" entry:
  var receptiveAppSettings = {
      "jwt": GENERATED_TOKEN
    }

As an example, in Ruby, using the 'jwt' gem, we could do the following:

An example to check against

You can test your code against this data to check it produces the correct token. If you need any help with this, please get in touch.

Step 3: Load the Receptive widget

Paste this JavaScript code before the closing </body> tag of your app and after the receptiveAppSettings snippet you built earlier.

As soon as you deploy your app with this JavaScript, Receptive will start populating your account with your user data.

Step 4: 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 widget 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 5: Let your customers log in (via portal or widget)

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

widgetvsportal.png

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:

suggest_a_feature_default_button.png

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":

Untitled_2.png

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})">Suggest Features</a>

 

Related:

See our security details here.

 

Any questions? Email support@receptive.io or use the form here.

 

 

 

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.