How to integrate Receptive with your product – Receptive.io

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.

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 1: Build your snippet
Step 2: How to sign your snippet (required only for secure mode)
Step 3: Load the Receptive widget
Step 4: Check your installation
Step 5: Let your customers log in (via portal or widget)

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 form`yyyy-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 form`yyyy-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	Required if using multi-modules	Modules that user is permitted to view. By default your customer users will only have access to the first (default) module 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"]}]
feature.products	Optional	Products automatically set on features created by the user specified in this snippet. Specified by an array of product ids.	["product-a", "product-b"]

View / download this data as a google doc

If you are using multi-modules:

Use the key for "user.allowed_products" above when creating or updating your snippet to grant appropriate end-user (customer) access.
The external ID for an existing module can be found here or go to Settings > Modules and select "Manage modules". The ID is in parenthesis to the right of the module name.
Leaving out the 'allowed_products' field in the snippet will leave the module settings for each user as currently set.
To remove module access from users, you will need to specify an empty list as their allowed_products field. (However each user will always need at least one module associated, and if set to an empty list in the snippet, then the default (first) module will be assigned to the user.)

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:

Take the data in the snippet
Generate a JSON Web Token using the 'HS256' algorithm
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.

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.

0 Comments