Installing the Brightback.js snippet
Integrating Brightback into your site or app requires a technical install that starts with embedding the Brightback.js code snippet to the page where your cancel button lives, and then configuring how you will process cancels and offers.
When it comes to designing the cancel page experience itself, your site Admin will use the Brightback Experience Manager, working in conjunction with a Brightback solutions consultant to design the retention strategy, brand the page, and define loss aversion, offers, and survey questions.
Brightback.js Overview
You can email brightback.js installation instructions to your developer here.
How to get Brightback.js up and running in three steps:
- Embed the Brightback JS snippet to your site or app
- Add personalized data you want captured and sent to Brightback
- Link the code to your cancel or downgrade button
Testing Brightback.js from localhost:
By default and for security reasons, Brightback’s server does not respond to a cancel initiation(precancel) request from localhost. If you are implementing a Brightback precancel request from your local machine during development, you will need to temporarily map a domain to your localhost to verify the XHR request. Watch your network tab in the inspector to diagnose any additional issues.
127.0.0.1 localhost example.local
By default and for security reasons, Brightback’s server does not respond to a cancel initiation(precancel) request from localhost. If you are implementing a Brightback precancel request from your local machine during development, you will need to temporarily map a domain to your localhost to verify the XHR request. Watch your network tab in the inspector to diagnose any additional issues.
127.0.0.1 localhost example.local
While step one and three is all that’s required to get immediate benefits from Brightback, step two will provide a richer, more personalized experience for your customers. Pro tip: scroll to the bottom of this article to see a "Bare Minimum" installation.
1. Embedding the Brightback.js snippet in your site or app
Installation for the Brightback JS snippet will vary for regular web apps and Single Page Apps. For single page app instructions, scroll to the bottom of this article. If your customers can have multiple subscriptions requiring a few possible cancel options, you’ll need to follow the Single Page App instructions.
<a id="bb-cancel" href="/fallback">Cancel</a> <script type="text/javascript" src="https://app.brightback.com/js/current/brightback.js"></script> <script type="text/javascript"> if (window.Brightback) { window.Brightback.handleData({ app_id: 'APP_ID', email: 'jdoe@example.com', save_return_url: '', cancel_confirmation_url: '', account: { internal_id: '1234AZ55' } }); } </script>
if (window.Brightback) { window.Brightback.handleData({ app_id: 'APP_ID', email: 'jdoe@example.com', account: { internal_id: '1234AZ55' } }); }<br>
Brightback Standard Fields
app_id |
This is your unique app ID that tells Brightback which company’s cancellation experience to display. You can get your app ID from your dedicated CSM |
The subscription id of your Customer in your billing system | |
full_name | Customer's Full Name |
<!-- Brightback | the customer retention company --> <!-- * = required fields --> <script type="text/javascript" src="https://app.brightback.com/js/current/brightback.js"></script> <script type="text/javascript"> if (window.Brightback) { window.Brightback.handleData({ app_id: 'APP_ID', first_name: 'John', last_name: 'Doe', email: 'jdoe@example.com', save_return_url: 'https://site.com/account/', cancel_confirmation_url: 'https://site.com/account/cancel', account: { company_name: 'Acme Products', company_domain: 'acme.com', internal_id: '1234AZ55', billing_id: 'cus_FfV4CXxpR8nAqB', plan: 'enterprise', value: 1000.00, created_at: 1312182000 } }); } </script>
under the "account" section of the code:
company_domain | Your canceling Customer’s website. Recommended for reporting for B2B businesses. |
internal_id | Your Customer's unique id |
Example snippet of a complete code below:
<!-- Brightback | the customer retention company --> <!-- * = required fields --> <script type="text/javascript" src="https://app.brightback.com/js/current/brightback.js"></script> <script type="text/javascript"> if (window.Brightback) { window.Brightback.handleData({ app_id: 'APP_ID', first_name: 'John', last_name: 'Doe', email: 'jdoe@example.com', save_return_url: 'https://site.com/account/', cancel_confirmation_url: 'https://site.com/account/cancel', account: { company_name: 'Acme Products', company_domain: 'acme.com', internal_id: '1234AZ55', billing_id: 'cus_FfV4CXxpR8nAqB', plan: 'enterprise', value: 1000.00, created_at: 1312182000 }, custom: { activity: { emails: 42085, // For loss aversion card templates: 86, // Values populated via a back-end contacts: 102546 // } } }); } </script>
custom: { activity: { emails: 42085, // For loss aversion card templates: 86, // Values populated via a back-end contacts: 102546 // } }
3. Link the code to your cancel button
<a id="bb-cancel" href="/fallback">Cancel</a><br></span>
Appendix
Installing the code into a Single-Page App
If your app is characterized by asynchronous JS and few page refreshes, you may need to integrate Brightback in a slightly different way. See the snippet in action here: Brightback Single Page App JSFiddle
Include the Brightback JS library file in your HTML head element or however your framework (React, Angular, etc.) sets up the environment. This will bind a few functions to window.Brightback
.
When your application is in a state where the user is presented with the cancelation option, you should setup the Brightback state, so that you can send the user immediately to the Brightback experience when the user clicks. This is achieved by sending the user's data to the window.Brightback.handleDataPromise
method.
For example:
const p = window.Brightback.handleDataPromise({ app_id: 'APP_ID', first_name: 'John', last_name: 'Doe', email: 'jdoe@example.com', save_return_url: 'https://site.com/account', cancel_confirmation_url: 'https://site.com/account/cancel', account: { company_name: 'Acme Products', company_domain: 'acme.com', internal_id: '1234AZ55', billing_id: 'cus_FfV4CXxpR8nAqB', plan: 'enterprise', value: 1000.00, created_at: 1312182000 }, custom: { activity: { emails : 42054, templates : 81, contacts : 102444 } } });
This will return a promise to a JSON validation object. The purpose of this step is to verify Brightback has sufficient data to render a cancelation experience prior to attempting to redirect the user. A successful validation object will look like this example:
{ "valid": true, "url": "https://app.brightback.com/examplecompany/cancel/LAz4pVyRkq" }
When the user clicks on your cancel button, you could redirect them as in the following example:
p.then((success) => { if (success.valid) { window.location.href = resp.url; } else { //use your current cancelation flow } });
Example of a "bare minimum" installation
The following is an example of the data that is strictly required for the integration to function properly. While some of the personalization and loss aversion would fall back to defaults, this represents the a place to start to get immediate value from an integration:
<a id="bb-cancel" href="/fallback">Cancel</a> <script type="text/javascript" src="https://app.brightback.com/js/current/brightback.js"></script> <script type="text/javascript"> if (window.Brightback) { window.Brightback.handleData({ app_id: 'APP_ID', email: 'jdoe@example.com', account: { internal_id: '1234AZ55' } }); } </script>
Just replace the APP_ID, and populate the email of the user and internal id of your customer's account, and you're ready to go!