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
NOTE: If you have a Receptive account, or access to one, then you can head to Settings > Install Receptive, and simply follow the personalized instructions there.
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>
If you are using 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 by going 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.)
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="pendo.feedback.loginAndRedirect()">Suggest Features</a>
or to load Receptive in a new tab, use the following:
<a href="#" target="_blank" onclick="pendo.feedback.loginAndRedirect({anchor: this}); return false;">Suggest Features</a>
Related:
See our security details here.
Comments
0 comments
Please sign in to leave a comment.