Installing the Brightback.js snippet

Initializing a session for your canceller in Brightback starts by making a precancel request to Brightback and sending your user to the unique session URL that is returned in the response. 

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 or by making a precancel request, and then configuring how you will process cancels and offers. 

When it comes to designing the cancel page experience itself, your Admin will use the Brightback Experience Manager to design the retention strategy, brand the page, and define loss aversion, offers, and survey questions. 

Brightback.js Overview

The brightback.js snippet runs when your customer clicks the cancel button and returns the URL of a customized cancel page to redirect your user to, while working all sorts of magic like a) pulling custom data in about your canceling customer, b) using that custom data to personalize the cancel experience (e.g. present dynamic offers, loss aversion carts, or alerts), and c) segmenting your customer based on standard or custom data fields. 

Here's a visual of how we use the Brightback JS snippet to personalize your Brightback Page.

You can email brightback.js installation instructions to your developer here.

How to get Brightback.js up and running in three steps:

  1. Embed the Brightback JS snippet to your site or app on the page where your customer will click cancel (e.g. account settings/management).  
  2. Add custom data fields to enrich customer records, create audiences, and personalize content in Brightback (see Brightback suggested data fields)
  3. 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 or use a tunnel service like ngrok or localtunnel. 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. 

Regular web apps

To add Brightback to your cancellation flow, start with this minimal code to paste in the head code, just before the </body> tag on the page where your Cancel button lives. See the snippet in action here: Brightback Regular App JSFiddle 
<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>
Replace the APP_ID with your company’s unique ID, which you can request from your CSM, and populate the email of the user and internal_id of your customer's account. 
The minimum fields required to generate a Brightback cancel experience without a billing provider enrichment are as follows: 
  if (window.Brightback) {
    window.Brightback.handleData({
     app_id: 'APP_ID',
     email: 'jdoe@example.com',
     account: {
      internal_id: '1234AZ55'
     }
    });
  }<br>

What are the standard brightback.js snippet fields? 

Standard data fields in Brightback 

 Name
 Description
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
subscription_id 
The subscription id of your Customer in your billing system (Stripe, Recurly, Chargebee)

first_name
Customer’s First Name
last_name
Customer’s Last Name
full_name Customer's Full Name
email
Customer’s Email

save_return_url

Return URL from Brightback for Customers who click Never mind.

cancel_confirmation_url

Return URL from Brightback for Customers who cancel. 

2. Add personalized data to capture and send to Brightback

If you want a richer cancellation experience for your customers, customize your code with desired customer attributes.
Adding customer attributes allows for:
  • Customizing customer data for a personalized experience
  • Grouping customers based on custom attributes (like big spenders vs. freebies)
  • Reporting for deeper insights
To add more data for personalization, simply edit your JS snippet to include those fields. Once you define which fields you’d like to include with your Customer Success Manager, we’re happy to generate your unique code so all you need to do is copy and paste just before the closing </body> tag on the page where your Cancel button lives.  
An example snippet looks like this: 
<!-- 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',
	plan_term: 'monthly',               
        value: 1000.00,                   
        created_at: 1312182000            
      }
    });
  }
</script>

Here’s a list of some built in, but optional , Standard Fields we recommend pulling in under the "account" section of the code:
  Field
  Description
company_name
Your canceling Customer’s company name. Recommended for reporting for B2B businesses.
company_domain Your canceling Customer’s website. Recommended for reporting for B2B businesses.
plan_term 
The renewal period for the subscription (yearly, weekly, monthly)
created_at
When your Customer started the subscription. Helpful to capture for creating customer age profiles.
internal_id Your Customer's unique id 
plan 
Used for reports or creating personalized offers by plan type, like enterprise or freemium
plan_term Your customer's billing term, e.g. monthly, weekly, annual
billing_id 
Used to identify Customers if using a Brightback-supported billing system like Stripe or Recurly 
value Revenue number to be displayed in reports or used for audiences.

Adding Custom Data

Each business is unique, and that means providing unique cancellation experiences based on how it’s important for your business to categorize your customers. Learn more about which custom data fields Brightback suggests to tailor Brightback for your subscription business. 
Once fields are defined, add to your Brightback JS snippet in a custom section below the default fields. 
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',
      full_name: 'John 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',
	plan_term: 'monthly',               
        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>
You’ll find the custom attributes defined in the custom section of the code: 
 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

To redirect your canceling customer through the Brightback cancellation experience, identify the button or link that is clicked by the user when initiating a cancelation request. Give the cancel link or button in your app an id of bb-cancel . Brightback will replace the href if we are able to render an exit experience based on the provided data following the call to window.Brightback.handleData . You should maintain a fallback that conforms with your existing workflow in the case that Brightback is unable to render an exit experience. 
<a id="bb-cancel" href="/fallback">Cancel</a><br></span>

Appendix

Making precancel requests without using Brightback.js

Brightback.js is not required in order to create cancel sessions in Brightback.  You may also make your own POST request to our precancel endpoint.  So long as you include the required properties and a valid app_id our server will respond with a unique session URL for your user.  More information can be found here.

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',
      full_name: 'John 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',
	plan_term: 'monthly',               
       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 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!

Example of a "bare minimum" installation with a supported billing system

If you are using Stripe, Recurly, or Chargebee, you'll only need to send the subscription id of the cancel request.  That will allow us to look up your user, cancel their subscription, or apply any offers if applicable. 

<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',
      subscription_id: '96SL3sJRIRmi8KJWR'
    });
  }
</script><br>

Loading Brightback experiences in an iframe.  

Wrapping the Brightback experience in an iframe is possible but due to our security policy, you must have a vanity domain in place that matches the TLD of the referring site.   

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us

Related Articles