Catch.js

👍
Interested In Integrating With Catch?
To make use of the tools described in this documentation, you will need a merchant account with Catch. Please reach out to our merchant partnerships team ([email protected]).

Overview

Catch.js provides drop in widgets to quickly and easily add Catch messaging across your site.

This demo page provides a showcase of Catch.js's UI widgets and other features in isolation. This may be used as a reference companion alongside this documentation.

Compatibility

Catch.js supports the following browsers versions:

Browser	Version
Chrome	94+
Firefox	92+
Edge	94+
Safari	14+
iOS Safari	14+
Android Browser	93+

Catch.js does not support Internet Explorer.

JavaScript must be enabled in the browser for Catch.js to work. Applications may use a <noscript> tag to display relevant messaging if JavaScript is disabled. For example:

<body>
  <noscript>
    <p>Please enable JavaScript to pay with Catch!</p>
  </noscript>
</body>

Catch.js is designed to be used within any modern Javascript framework, or may be used independent of a framework as well.

📘
TypeScript
It's possible to use Catch.js in TypeScript projects. If you wish to do so, we recommend using our Catch.js package, which is discussed below under Asynchronous Loading. This package includes type declarations for the SDK.

Loading

Catch.js is hosted on Catch's servers and designed to be loaded via a <script> tag directly from Catch's CDN:

<body>
  <script src="https://js.getcatch.com/catchjs/v1/catch.js"></script>
</body>

Synchronous Loading

Catch.js should be loaded synchronously when using this method of loading via a <script> tag. In other words, applications should not set a defer or async attribute on the Catch.js <script> tag. To avoid blocking critical parts of the document from rendering, we recommend including this <script> tag towards the end of the <body> element.

Asynchronous Loading

If asynchronous loading is required, please reach out to your Catch technical contact for more information.

Initialization

When Catch.js first loads and executes, a single object named catchjs is placed in the global namespace. Once Catch.js has been loaded, the SDK must be initialized for a specific merchant by calling the function catchjs.init() (this function should be invoked exactly once during the lifecycle of the application).

<body>
  <script src="https://js.getcatch.com/catchjs/v1/catch.js"></script>
  <script>
    catchjs.init("<merchant_public_key_value>", {
    	// Optional configuration settings
    });
  </script>
</body>

catchjs.init accepts two parameters: publicKey and options. The publicKey is required and should be a string representing the merchant's public API key. options is an object which specifies optional configuration settings to control global behavior of the SDK.

Catch.js's initialization routine is asynchronous. catchjs.init() returns a Promise which resolves once the SDK has successfully initialized, and rejects if there was an error that prevented initialization from completing.

If the provided publicKey is invalid, initialization will not succeed. Applications may handle this scenario by catching the Promise returned by catchjs.init():

catchjs.init("invalid publicKey").catch(function (error) {
  // Initialization failed :(
});

try {
  await catchjs.init("invalid publicKey");
} catch (error) {
  // Initialization failed :(
}

📘
Viewing the Live Demo With Your Public Key
By default, the Live Demo initializes Catch.js for a test merchant (Merch by Catch). Alternatively, you may view the demo using a different merchant's valid public key, by loading the live demo page with the ?publicKey=<merchant public key value> querystring parameter.

Initialization options

The options object passed as the second argument to catchjs.init() may provide the following key/values. If an option key is not defined, or options is omitted entirely, Catch.js will fallback to a default value for the option.

Key name	Type	Default value	Description
`pageType`	`string` which is one of the following supported values: "unknown", "home", "product", "mini-cart", "cart", "checkout"	"unknown"	Specifies the type of page in which Catch.js is currently running. This should be set to the most applicable value if the page type fits with one of the available page type choices. The "unknown" page type may be used when there isn't a more specific page type that fits.
`theme`	`string` which is one of the following values: "light-color", "light-mono", "dark-color", "dark-mono".	"light-color"	Specifies the default theme which determines the look and feel of widgets, from a set of available predesigned options. The "light-color" theme is intended for widgets which are displayed over a light background, and features Catch's branding color scheme. The "light-mono" theme is also intended for light backgrounds, but renders a monochromatic foreground color. The "dark-color" and "dark-mono" themes are analogous to the light themes, but intended for widgets which are displayed over a dark background. Widgets will render using the default theme by default, but a theme may also be designated for an individual widget via a `theme` attribute.

Catch Handle API

The handle object that's returned when catchjs.init() resolves provides the following functions:

Function signature	Description
`setPageType(pageType: string): void`	Changes the current value of the page type. The `pageType` parameter accepts the same enumeration of values that can be used for the `pageType` option when initializing the SDK. Applications should call this function if the page type changes at any point after the SDK has been initialized (for example, when navigating to another page without triggering a full page reload).
`setTheme(theme: string): void`	Changes the current value of the default theme. The `theme` parameter accepts the same enumeration of values that can be used for the `theme` option when initializing the SDK.

📘
Custom Themes
Some merchants may have a "custom" theme associated with their account. When Catch.js is used for a merchant with a custom theme, it will automatically use the settings specified by the custom theme to determine the look and feel of all widgets. In this case, setting one of the built-in themes (via the theme initialization option or the catchHandle.setTheme() function as described above) will have no effect.

UI Widgets

Overview

The HTML tags for all UI widgets may be used anywhere in the HTML document where flow content is accepted (i.e. anywhere where it would be acceptable to use a <div>, for example). It is possible to include the HTML for a Catch.js widget before the SDK has actually been initialized. For example, the following HTML markup demonstrates a Callout widget (whose tag is <catch-callout>) being used in the document ahead of loading and initializing the SDK (in this hypothetical example, we imagine the Callout widget being used on a product detail page):

<body>
  <div class="product-details">
    <h1>T-shirt</h1>
    <h2>$50</h2>
    <catch-callout price="5000" />
  </div>
  
  <script src="https://js.getcatch.com/catchjs/v1/catch.js"></script>
  <script>
    catchjs.init("<merchant public key value>", {
    	pageType: "product"
    });
  </script>
</body>

Styling widgets pre and post initialization

Prior to complete initialization of Catch.js, the custom element (in this example, <catch-callout>) will be rendered by the browser in an undefined state, and not display any Catch.js-specific content or CSS (in effect, appearing essentially as if the element were an empty <div>). Applications may choose to provide their own styling for these elements while they are still undefined (or not display widgets at all until after initializing the SDK). In the following example CSS, styling is applied to Callout widgets which are undefined in order to have them appear as a gray box while Catch.js is still loading:

catch-callout:not(:defined) {
  display: block;
  height: 28px;
  background: gray;
}

After Catch.js initialization has completed, all custom elements defined by the SDK are switched into a defined state, and provide the full content, styling, and behaviors implemented by the SDK. As desired, applications may choose to apply their own CSS to defined custom elements as well (for example, to control things like margins around the widgets).

catch-callout:defined {
  margin: 10px 0;
}

Callout (`<catch-callout>`)

<catch-callout
  price="23000"
  border-style="pill"
  or-prefix
  page-type="mini-cart"
  theme="light-mono"
/>

The Callout widget shows consumers how much Catch credit they could earn or redeem based on the price of the item(s) they're considering (e.g. when viewing a product detail page or their cart). The widget also includes a trigger that, when clicked, opens a modal which displays more detailed informational content about paying with Catch and earning rewards on the merchant's site. The widget automatically recognizes consumers who are currently signed in to Catch, and tailors the messaging to them if they have rewards that are available to redeem with the merchant.

The Callout widget also makes use of its price attribute to calculate rewards the user will earn on the current item (if implemented on product detail page) or on the current order (if implemented in the cart or during the checkout flow).

Attributes

The following attributes are used to customize the behavior of an instance of <catch-callout>:

Attribute name	Type	Required?	Default value	Description
`price`	`number`	No		The cost in cents that a consumer would pay for the item(s) without redeeming Catch credit. If not set, the widgets will display the rewards rate (e.g. “Earn 10% credit”) rather than a specific rewards value (e.g., "Earn $24.00 credit"). If provided, the `price` must be a positive number. A negative `price` will be treated as if the `price` is not set at all.
`border-style`	`string` which is one of the following values: "default", "pill", "square", "none", "none-no-padding"	No	"default"	The style of border the widget renders. Defaults to `default`, a rectangular (slightly rounded) border around the widget. `pill` renders a rounded border around the widget. `square` renders a border without rounded corners. `none` renders the widget without a border. `none-no-padding` renders the widget without a border, and also removes the padding around the widget text (whereas the `none` border style keeps the padding).
`or-prefix`	`boolean`	No	`false`	If `or-prefix` is set, the word "or" is prepended into the displayed messaging (e.g. "or earn $23.00 credit" instead of "Earn $23.00 credit".
`page-type`	`string` which is one of the following supported values: "unknown", "home", "product", "mini-cart", "cart", "checkout"	No		A widget-specific "page type". Normally, the current page type in Catch.js is set globally through the `pageType` option when initializing the SDK, or by calling the `setPageType()` function on a Catch handle object. Optionally, the `page-type` attribute may be used to override the global page type at the individual widget level. This is intended for Callout widgets that are displayed in a modal/overlay where the context they're displayed in can be described with a more specific page type than the current global one. For example, on a merchant's PDP, it is expected the application will set the global page type to "product". If, however, that page also displays a Callout widget in a cart that's opened on the page as an overlay, the application should set a `page-type` on that specific widget to "mini-cart".
`theme`	`string` which is one of the following values: "light-color", "light-mono", "dark-color", "dark-mono".	No		A "theme" to be used for displaying this Callout instance. If this attribute is not set, the widget will render using the default theme. This attribute is ignored if the merchant is using a custom theme.

📘
Attributes and reactivity
All custom attributes for all Catch widget elements are reactive. If a given widget's attribute's value is changed after the the widget is already rendered, the widget will automatically detect this and update its display accordingly.
With Callout widgets, for example, applications may dynamically set the value of the price attribute should the relevant price change. One scenario where we anticipate this may be applicable is when a Callout is displayed in a cart, and the total price reflected by the cart changes as the consumer adds/removes items.

📘
Currency support
Catch.js currently displays all money amounts (based on attribute values such as price) in US dollars. Future versions of the SDK may be extended to support additional currencies.

🚧
Prices are specified in cents, not dollars
Please note that all price values in Catch.js are specified in cents. Widgets will not behave correctly if their price attributes are based on dollars. For example, if the price of a product is 100 dollars, than the value set in the price attribute for a corresponding Callout widget should be "10000", not "100".

Express Checkout Callout (`<catch-express-checkout-callout>`)

<catch-express-checkout-callout
  price="23000"
  border-style="square"
/>

The Express Checkout Callout widget displays similar informational content as the Callout with additional messaging on where to find Catch in the checkout flow. It is intended to be displayed in merchant checkout flows in which an express checkout option is present--since Catch can only be selected on the final step of checkout, this messaging is meant to reduce confusion if the consumer intends to pay with Catch but does not see it displayed as an express checkout option. The widget also includes a button to open an informational modal with more detailed literature about paying with Catch and with links to visit Catch's marketing website.

The Express Checkout Callout widget also makes use of its price attribute to calculate rewards the user will earn on the current purchase.

Attributes

The following attributes are used to customize the behavior of an instance of <catch-express-checkout-callout>:

Attribute name	Type	Required?	Default value	Description
`price`	`number`	No		Provides the same behavior as the `price` attribute on the Callout widget.
`border-style`	`string` which is one of the following values: `"default"`, `"pill"`, `"square"`, `"none"`, `"none-no-padding"`	No	`"default"`	The style of border the widget renders. Defaults to `default`, a rectangular (slightly rounded) border around the widget. `pill` renders a rounded border around the widget. `square` renders a border without rounded corners. `none` renders the widget without a border. `none-no-padding` renders the widget without a border, and also removes the padding around the widget text (whereas the `none` border style keeps the padding).
`theme`	`string` which is one of the supported `theme` values that can be passed when initializing the SDK or invoking the `catchHandle.setTheme()` function.	No		A "theme" to be used for displaying this Express Checkout Callout instance. If this attribute is not set, the widget will render using the default theme. This attribute is ignored if the merchant is using a custom theme.

Campaign Link (`<catch-campaign-link>`)

<catch-campaign-link
  campaign-name="POST-CHECKOUT"
  anchor-target="_blank"
  theme="light-color"
  prefill-name="John Doe"
  prefill-email="[email protected]"
  prefill-phone="8885551437"
/>

The Campaign Link widget fetches an active Catch campaign corresponding to campaign-name. The widget is designed to be used on your order confirmation page if Catch was not used as a payment method to offer credits the next time the consumer pays with Catch.

The widget includes information about how much Catch credit the consumer can claim based on the reward campaign’s metadata and acts as a hyperlink, directing consumers who interact with it to a page on which they can claim their credits.

Prefill

Like the checkout flow, the catch-campaign-link widget supports prefilling customer information. Within Catch's signup flow, consumers are asked to input their phone number, name, and email address. Because it's often the case that the consumer would have already filled out this info on the merchant's site (for example, when filling out their shipping info), this widget allow the applications to specify these values ahead of opening the claim campaign link, so that they are pre-filled in Catch's UI and the consumer doesn't have to re-enter them.

Attributes

The following attributes are used to customize the behavior of an instance of <catch-campaign-link>:

Attribute name	Type	Required?	Default value	Description
`campaign-name`	`string` which is the name of a valid campaign configured through Catch.	Yes		The name of a valid and active Catch campaign, provided to you by the Catch team.
`anchor-target`	`string` which is a valid value for the `target` attribute of a standard `<a>` element, such as "_self" or "_blank".	No	`"_blank"`	The value to use for the `target` attribute on the `<a>` element the widget displays to link consumers to their account page on Catch. For example, this attribute may be set to "_self" to open the link in the same tab.
`theme`	`string` which is one of the supported `theme` values that can be passed when initializing the SDK or invoking the `catchHandle.setTheme()` function. This attribute is ignored if you are using a custom theme.	No		A "theme" to be used for displaying this Purchase Confirmation instance. If this attribute is not set, the widget will render using the default theme. This attribute is ignored if the merchant is using a custom theme.
`prefill-name`	`string`	No		A string value to prefill the user's full name on Catch's signup UI flow
`prefill-email`	`string`	No		A string value to prefill the user's email address on Catch's signup UI flow
`prefill-phone`	`string` of 10 characters exactly	No		A string value to prefill the user's phone number on Catch's signup UI flow

Catch Logo (`<catch-logo>`)

<catch-logo
  size="sm"
/>

The Catch Logo widget displays Catch's logo. To control the size of the widget, you can use the size property for two pre-determined dimensions. To control the size of the logo on a more granular level, omit the size property from the widget entirely and style its dimensions as necessary.

Attributes

The following attributes are used to customize the appearance of an instance of <catch-logo>:

Attribute name	Type	Required?	Default value	Description
`size`	`string` which is one of the following values: `sm` or `md`	No		The size of the rendered Catch logo. `sm` will render an 18px x 57px logo, `md` will render a 40px x 116px logo, and leaving the attribute undefined will allow the logo to fill its containing element
`theme`	`string` which is one of the supported `theme` values that can be passed when initializing the SDK or invoking the `catchHandle.setTheme()` function. This attribute is ignored if the merchant is using a custom theme.	No		A "theme" to be used for displaying this Catch Logo instance. If this attribute is not set, the widget will render using the default theme. This attribute is ignored if the merchant is using a custom theme.

Performance

Catch.js is designed to minimize impacts on site performance while providing you access to the key functionality your site gets from the SDK. Check out our FAQs for information on the steps we take to optimize performance.

Experimentation

These docs describe the default appearance of Catch widgets. To improve our product, Catch may run experiments that alter the appearance of some widgets, and some variants may not use some of the variables that a merchant has set.

Catch.js

👍
Interested In Integrating With Catch?

Overview

Compatibility

📘
TypeScript

Loading

Synchronous Loading

Asynchronous Loading

Initialization

📘
Viewing the Live Demo With Your Public Key

Initialization options

Catch Handle API

📘
Custom Themes

UI Widgets

Overview

Styling widgets pre and post initialization

Callout (`<catch-callout>`)

Attributes

📘
Attributes and reactivity

📘
Currency support

🚧
Prices are specified in cents, not dollars

Express Checkout Callout (`<catch-express-checkout-callout>`)

Attributes

Campaign Link (`<catch-campaign-link>`)

Prefill

Attributes

Catch Logo (`<catch-logo>`)

Attributes

Performance

Experimentation

👍Interested In Integrating With Catch?

Overview

Compatibility

📘TypeScript

Loading

Synchronous Loading

Asynchronous Loading

Initialization

📘Viewing the Live Demo With Your Public Key

Initialization options

Catch Handle API

📘Custom Themes

UI Widgets

Overview

Styling widgets pre and post initialization

Callout (<catch-callout>)

Attributes

📘Attributes and reactivity

📘Currency support

🚧Prices are specified in cents, not dollars

Express Checkout Callout (<catch-express-checkout-callout>)

Attributes

Campaign Link (<catch-campaign-link>)

Prefill

Attributes

Catch Logo (<catch-logo>)

Attributes

Performance

Experimentation

👍
Interested In Integrating With Catch?

📘
TypeScript

📘
Viewing the Live Demo With Your Public Key

📘
Custom Themes

Callout (`<catch-callout>`)

📘
Attributes and reactivity

📘
Currency support

🚧
Prices are specified in cents, not dollars

Express Checkout Callout (`<catch-express-checkout-callout>`)

Campaign Link (`<catch-campaign-link>`)

Catch Logo (`<catch-logo>`)