Clearpay Dynamic Messaging Widget

🚧

Availability

Clearpay Dynamic Messaging Widget is currently only available in the UK and in Afterpay Regions.
For Clearpay EU please continue to use our JavaScript Library.

The Clearpay Dynamic Messaging widget allows you to display the standard Clearpay messaging together with Clearpay promo messaging during the shopping experience. The messaging can be shown on product pages, the cart, and the checkout pages.

Integrating dynamic messaging for the first time

  1. Add the following code snippet in the <head> section of your product, cart, and checkout web pages:
<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
  1. Initialise the widget by adding the following code into the <body> of any page you wish to display Clearpay messaging. We recommend that on product pages the messaging is immediately below the price, on cart pages the messaging is below the subtotal, and on checkout pages, the messaging is within the Clearpay payment option.
<div id="afterpay-messaging-widget"></div>
  1. Add the following code into your web pages to configure the look and feel of the widget:
<script>
    function createMessaging () {
        new AfterPay.Widgets.Placement({
            // Ensure target matches the id specified in step 3
            target: "#afterpay-messaging-widget",
            locale: "en-GB",
            // Change to match the page you want to display the widget on
            context: "PRODUCT_PAGE",
             // Change to the public key provided to you by the Clearpay          
             // team
            publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
            attributes: {
                currency: "GBP",
                amount: "300",
                promoRenderStyle: “promo-with-get-and-payments”, 
            }
        });
    }
</script>
  1. Configure the widget to suit your implementation. Locale, currency, context, and render style should be adjusted as necessary. For more information, see configuring the dynamic widget.

Replacing an existing Clearpay messaging widget

To replace an existing Clearpay messaging widget with the dynamic widget, follow these steps:

  1. Add the following code to the <head> element of your web pages:
<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
  1. In your web page HTML, find and copy the afterpay placement element. It should look something like this:
<afterpay-placement
    data-amount="300"
    data-locale="en_GB"
    data-currency="GBP">
      data-...
</afterpay-placement>
  1. Open the dynamic widget migration helper and enter your public key, region, context, and paste the code snippet copied in the last step into the Current tag: section.
  2. Copy the code in the New placement javascript field.
  3. Add the following code snippet to the <head> section of your web page, and paste in the code copied in the previous step:
<script>
    function createMessaging () {
    // Paste new placement code from step 4 here
    }
</script>
  1. Initialise the widget by adding the following code into the <body> of any page you wish to display Clearpay messaging. We recommend that on product pages the messaging is immediately below the price, on cart pages the messaging is below the subtotal, and on checkout pages, the messaging is within the Clearpay payment option.
<div id="afterpay-messaging-widget"></div>
  1. Search for and delete the following code snippet:
<script src="https://js.afterpay.com/afterpay-1.x.js" data-analytics-enabled async></script>
  1. Search for and delete the <afterpay-placement> tag and all code inside it. It will probably look similar to the following code snippet:
<afterpay-placement
    data-amount="300"
    data-locale="en-GB"
    data-currency="GBP">
      data-...
</afterpay-placement>

Configuring the dynamic messaging widget

There are a number of configuration options that can be adjusted .

Attribute name

Type

Supported values

Description

target

string, required

A CSS selector that matches an element on your site, for example, #afterpay-messaging-widget

locale

string, required

en-US
en-AU
en-CA
en-GB
en-NZ

Description of your store region.

context

string, required

PRODUCT_PAGE
CART
CHECKOUT
ORDER_CONFIRMATION

The type of page that this instance of the widget will appear on.

publicKey

string, required

Your Clearpay public key, for example 6e757026-0fcd-4fdc-a858-13017c8f584f

promoRenderStyle

string, optional

promo-only
promo-or-empty
promo-and-payments-or-empty
promo-and-payments
promo-with-get-and-payments-or-empty
promo-with-get-and-payments (default)

This attribute lets you select the style in which you want to display the promo messaging.

promoAnimationStyle

string, optional

blink
toggle
alternate-diagonals

This attribute lets you select the style of animation for the discount amount. You can select from three different variants.

styles

parent category, optional

see below for style attributes

Contains configurable style parameters.

Style configuration options

Style attribute

Type

Description

Examples

fontFamily

string, optional

The name of a font available to the browser.

Sans-Serif
Arial

fontFaces

string, optional

An array of all custom font faces that you intend to reference in the fontFamily definition.

See Font Faces section below.

linkColor

string, optional

A CSS color for links appearing in the placement.

red
rgb(123,123,123)

logoBadgeWidth

string, optional

The width of the Clearpay badge.

2em
15px

textAlign

string, optional

A valid CSS text-align value.

center
left
right
justify

textColor

string, optional

A CSS color for the text that appears in the placement (excludes the Clearpay logo and promo amount styles).

red
rgb(123,123,123)

Font Faces

The fontFaces style allows you to define one or many custom font faces that you will reference in your fontFamily definition for the widget.

The following defines the attributes of each font face option.

Attribute

Supported values

Examples

family

The custom name for your font. This field is required.

MyGreatFont

sources

An array of sources for your custom font face. This field is required.

See Font Sources section below.

ascentOverride

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override

normal
90%

descentOverride

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override

normal
90%

display

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-display

auto
block

featureSettings

See https://developer.mozilla.org/en-US/docs/Web/CSS/font-feature-settings

normal
revert

stretch

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch

expanded
100%

style

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style

normal
oblique 30deg

variant

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variant

small-caps
unset

variationSettings

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-variation-settings

normal
"xhgt" 0.7

weight

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight

400
bold

unicodeRange

See https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range

U+26
U+0025-00FF

Here is a full example of a font face definition.

new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-GB",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "GBP",
        amount: "300"
        styles: {
            fontFamily: "CustomFont1, CustomFont2, sans-serif",
            fontFaces: [
              {
                family: "CustomFont1",
                sources: [
                  {
                    url: "https://example.com/CustomFont1.woff2",
                    format: "woff2"
                  },
                  {
                    url: "https://example.com/CustomFont1.woff",
                    format: "woff"
                  },
                  {
                    local: "-apple-system"
                  }
                ],
                display: "swap",
                ascentOverride: "normal",
                descentOverride: "normal",
                featureSettings: "normal",
                lineGapOverride: "normal",
                stretch: "50% 200%",
                style: "oblique 20deg 50deg',
                variant: "small-caps",
                variationSettings: "normal",
                weight: 400
                unicodeRange: "U+26"
              },
              {
                family: "CustomFont2",
                sources: [
                  {
                    url: "https://example.com/CustomFont2.woff2",
                    format: "woff2"
                  }
                ]
            ]
        }
    }
});

Font Sources

A single font face can have a number of different sources. There are 2 kinds of font sources - a URL to a remote font, or a local font on a user’s computer.

Remote Font

Attribute

Supported Values

Examples

url

The URL to the remote font. This field is required.

https://somewebsite.com/path/to/font.woff

format

The format of the font.

woff
woff2

Local Font

Attribute

Supported Values

Examples

local

A local font name. This field is required.

-apple-system

Amount selector

The amountSelectors attribute is available as an alternative to the amount attribute, which allows you to select the content of an HTML element to use as the amount. This element will also be watched for any changes and the widget will be updated automatically. Here is an example of using this attribute:

new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-GB",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "GBP",
        amountSelectors: {
            amount: "#myamountelement"
        }
    }
});

Amount mutation selector

The mutation attribute, allows you to watch for changes in content on an element that is not the amount element, to trigger an update of the amount present in your selected amount element. This is useful if product amount changes on your site trigger a reload of a parent element to the amount, meaning mutations on the amount itself will not be fired. Here is an example of this.

new AfterPay.Widgets.Placement({
    target: "#afterpay-messaging-widget",
    locale: "en-GB",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "GBP",
        amountSelectors: {
            amount: "#myamountelement",
            mutation: "#someparentelement"
        }
    }
});

Target selector

The targetSelector attribute functions as an alternative to the target attribute and allows you to place the widget adjacent to an existing element using a CSS selector (a target HTML element to place the widget inside is not required). Here is an example of using this option:

new AfterPay.Widgets.Placement({
    targetSelector: {
        adjacentElement: "#myelement",
        placementPosition: "beforebegin"
    },
    locale: "en-GB",
    context: "PRODUCT_PAGE",
    publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
    attributes: {
        currency: "GBP",
        amount: "200"
    }
});

Valid values for the placementPosition option are the same as the valid position values defined here.

All configuration attributes of the static Clearpay messaging widget are applicable to the dynamic messaging widget, and can be found Afterpay.js Glossary .

🚧

When using these attributes in the JavaScript snippet, they should be converted from snake case to camel case. For example payment-amount-is-bold would become paymentAmountIsBold, show-upper-limit would become showUpperLimit.

Testing Promotion Messaging

When implementing the messaging widget, you may wish to manually enable a promotion to see how this appears on your site. When using the Sandbox version of afterpay.js you can enable promotion messaging using one of the following “test” public keys in your configuration.

Public Key

Behaviour

dollar-off-promotion

Shows a £20 off promotion.

🚧

This public key only works when using the Sandbox version of afterpay.js - it will not work with the production version.

Example:

<script src="https://portal.sandbox.afterpay.com/afterpay.js" async onload="createMessaging()"></script>

<script>
    function createMessaging () {
        window.messagingWidget = new AfterPay.Widgets.Placement({
            target: "#afterpay-messaging-widget",
            locale: "en-GB",
            context: "CART",
            publicKey: "dollar-off-promotion",
            attributes: {
                amount: "300"
            }
        });
    }
</script>