How to install the Chargebee Retention.js snippet? : Chargebee Help Center

Scope

How to install the Chargebee Retention.js snippet?

What are the steps to configure Chargebee Retention.js snippet?

What are the standard Chargebee Retention.js snippet fields?

Summary

Initializing a session for your canceller in Chargebee Retention starts by making a precancel request to Chargebee Retention and sending your customers to the unique session URL that is returned in the response. Integrating Chargebee Retention into your site or app requires a technical install that starts with embedding the Chargebee Retention.js code snippet to the page where your cancel button is configured or by making a precancel request, and then you can configure process cancels and offers by referring to this link.

There are 3 options to install the Chargebee Retention.js snippet

Step 1. Embedding the Chargebee Retention.js snippet in your site or app

Step 2. Add personalized data to capture and send to Chargebee Retention

Step 3. Link the code to your cancel button

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

Solution

Chargebee Retention.js Overview

The Chargebee Retention .js snippet runs when your customer clicks the cancel button and returns the URL of a customized cancel page to redirect your user to offers to retain your customers.

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)

c) Segmenting your customer based on standard or custom data fields.

Here's an image of how we use the Chargebee Retention JS snippet to personalize your Chargebee Retention Page.

You can email Chargebee Retention.js installation instructions to your developer from this link.

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

Embed the Chargebee Retention JS snippet to your site or app on the page where your customer clicks cancel (e.g. account settings/management).
Add custom data fields to enrich customer records, create audiences, and personalize content in Chargebee Retention (see Chargebee Retention suggested data fields)
Link the code to your cancel or downgrade button

Testing Chargebee Retention.js from localhost:
By default and for security reasons, Chargebee Retention’s server does not respond to a cancel initiation (precancel) request from localhost. If you are implementing a Chargebee Retention 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

Step 1 & Step 3 has instructions required to get immediate benefits from Chargebee Retention and Step 2 has instructions for a personalized experience for your customers. Scroll to the bottom of this article for 'Bare Minimum' installation instructions.

Step 1. Embedding the Chargebee Retention.js snippet in your site or app

Installation for the Chargebee Retention JS snippet will vary for Regular web apps & 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 Chargebee Retention 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. Refer to this link for the Chargebee Retention Snippet sample.

<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: 'YOUR_BRIGHTBACK_APP_ID',
    email: 'UNIQUE_USER_EMAIL,
    save_return_url: '',
    cancel_confirmation_url: '',
    account: {
      internal_id: 'UNIQUE_USER_ID'
    }
  });
  }
</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 Chargebee Retention cancel experience without a billing provider enrichment are as follows:

  if (window.Brightback) {
    window.Brightback.handleData({
     app_id: 'YOUR_BRIGHTBACK_APP_ID',
     email: 'UNIQUE_USER_EMAIL',
     account: {
      internal_id: 'UNIQUE_USER_ID'
     }
    });
  }<br>

What are the standard Chargebee Retention.js snippet fields?

Standard data fields in Chargebee Retention

Field	Description
app_id	This is your unique app ID that tells Chargebee Retention 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 Chargebee Retention for Customers who click Never mind.
cancel_confirmation_url	Return URL from Chargebee Retention for Customers who cancel.

If you want a personalized cancellation experience for your customers, customize your code with desired customer attributes.

Step 2. Add personalized data to capture and send to Chargebee Retention

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',                      //*  
      subscription_id: 'SUB_ID'              //*               
      first_name: 'John',                 
      last_name: 'Doe',                   
      email: '[email protected]',          
      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: 'USER_ID',              //* 
        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:

When your Customer started the subscription. Helpful to capture for creating customer age profiles.

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
billing_id	Customer billing id
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 Chargebee Retention suggests to tailor Chargebee Retention for your subscription business.

Once fields are defined, add to your Chargebee Retention 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: '[email protected]',          
      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                //
   }
 }

Step 3. Link the code to your cancel button

To redirect your canceling customer through the Chargebee Retention 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. Chargebee Retention 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 Chargebee Retention is unable to render an exit experience.

<a id="bb-cancel" href="/fallback">Cancel</a><br></span>

Appendix

Making precancel requests without using Chargebee Retention.js

Chargebee Retention.js is not required in order to create cancel sessions in Chargebee Retention. 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 at this link.

Installing the code into a Single-Page App

If your app is characterized by asynchronous JS and a few page refreshes, you may need to integrate Chargebee Retention in a slightly different way. See the snippet in action here: Chargebee Retention Single Page App JSFiddle

Include the Chargebee Retention 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 set up the Chargebee Retention state, so that you can send the user immediately to the Chargebee Retention 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: '[email protected]',          
      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 that Chargebee Retention 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 customer 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: '[email protected]',
      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 all set.

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 Chargebee Retention experiences in an iframe.

Wrapping the Chargebee Retention 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.

Related Articles

How to set up a Vanity URL in Chargebee Retention?

What is Loss Aversion cards in Chargebee Retention?

How to create a new offer in Chargebee Retention?

How to edit your Chargebee Retention Cancel Page?

Knowledge center

How to install the Chargebee Retention.js snippet?

What are the standard Chargebee Retention.js snippet fields?

Step 1. Embedding the Chargebee Retention.js snippet in your site or app

Step 2. Add personalized data to capture and send to Chargebee Retention

Step 3. Link the code to your cancel button

Solution

Chargebee Retention.js Overview

Here's an image of how we use the Chargebee Retention JS snippet to personalize your Chargebee Retention Page.

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

Step 1. Embedding the Chargebee Retention.js snippet in your site or app

Regular web apps

What are the standard Chargebee Retention.js snippet fields?

If you want a personalized cancellation experience for your customers, customize your code with desired customer attributes.

Step 2. Add personalized data to capture and send to Chargebee Retention

An example snippet looks like this:

Here’s a list of some built-in, but optional, Standard Fields we recommend pulling in under the 'account' section of the code:

Adding Custom Data

Example snippet of a complete code below:

You’ll find the custom attributes defined in the custom section of the code:

Step 3. Link the code to your cancel button

Appendix

Making precancel requests without using Chargebee Retention.js

Installing the code into a Single-Page App

For example:

Example of a 'bare minimum' installation

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

Loading Chargebee Retention experiences in an iframe.

Related Articles