Rally's Developer Portal

Storefront

Follow the steps provided to integrate the Rally checkout button into your Storefront.

Replacement for your default checkout buttons

It takes you to Rally's checkout page(s) instead of the platform's default checkout page.

Storefront examples

You can install and set up Rally Checkout Button using either the NPM package or by including the script on the client side.

NPM Package

Install the package using npm:

Copy

Copied

npm install @rallycommerce/elements

Import the package and initialize:

Copy

Copied

import { Rally } from '@rallycommerce/elements';
Rally.init('clientId');

Client-side Script

Include the script and initialize:

Copy

Copied

<script src="https://js.onrally.com/elements/elements.js"></script>
<script>
  Rally.init('clientId');
</script>

Initialization and Session Configuration

When initializing Rally, you have the option to pass a configuration object as a second parameter to Rally.init(). This object allows you to configure various settings, such as a fallback URL or selector, disabling automatic redirects, enabling a custom click handler for the Rally checkout button to function as a buy now button, and more. For additional details, refer to the configuration options during initialization and the exposed API documentation.

Copy

Copied

const config = {
  flowSegments: ['storefront']
  fallbackUrl: '/checkout'
};

Rally.init('clientId', config);

Place the HTML markup into the template

The rendered "Checkout" button is created through markup, with its high customizability offered by the Rally.init and configuration properties mentioned later. To tailor and configure a specific instance of the element, adjust the relevant data attributes as needed (default values are used as examples).

Copy

Copied

<rally-checkout-button independentClickEventHandler="false" disabled="false" loading="false"
  custom-class="rally-btn" custom-text="Check out" custom-type="button" redirect="true" loader="false" cart-data='{"id": "cartId", "content": "cart", "currency": "cartCurrencyISO"}'>
</rally-checkout-button>

Handling Cart Data

Rally's checkout button offers various methods for providing the cart details, ensuring compatibility with a wide range of technologies.

Provide Cart Data via Data Attribute

You can provide the cart details by utilizing the cart-data attribute, which contains a stringified object as its value, encompassing properties like id, content, and currency. Make sure the value is responsive, ensuring the checkout button consistently contains the most recent cart state.

Copy

Copied

<rally-checkout-button cart-data='{"id": "cartId", "content": "cartContent", "currency": "cartCurrencyISO"}'></rally-checkout-button>

Apply Cart Data programmatically

You can supply the cart details using the Rally.applyCartData method, which requires an object featuring the properties id, content, and currency. Be sure to call the method whenever there are updates to the cart, so that the checkout button continuously operated with the most current cart state.

Copy

Copied

const cartData = {id: "cartId", currency: "cartCurrencyISOFormat", content: "cart"}
Rally.applyCartData();

Define the function for retrieving cart information

Define the function to obtain cart information by assigning it to Rally.platform.getCart. This function should return a promise that resolves with an object containing the properties id, content, and currency. By defining this function, the checkout button will always fetch the most recent cart data by invoking this function before proceeding with the redirection.

This example varies depending on the specific storefront being used

Incorporate the appropriate code snippet for the storefront you're using, and ensure it is included before calling the Rally init method.

Copy

Copied

(function (win, doc) {
  win.platform = {};

  win.platform.getCart = () => {
    return fetch('apiUrlForRetrievingCartId',
      { credentials: 'same-origin' })
      .then((response) => { return response.json(); })
      .then((cart) => { return cart ? { id: cart.id, currency: cart.currency.code, content: cart } : null; });
  }
})(window, document);

Styling the button

To style the button, provide the following data attributes to override the default value for custom-class

Copy

Copied

<rally-checkout-button custom-class="optional-custom-class"></rally-checkout-button>

To style other sub-elements of the button, override the following:

For the button's HTML element, use .rally-btn.

For the inner text content of the button, use .rally-btn-text.

For the spinner, use .rally-loader-wrapper, .rally-loader, and .rally-spinner.