Dynamic messaging widget
Availability
The Afterpay Dynamic Messaging Widget is currently available in Afterpay Regions and Clearpay UK.
In order to use the dynamic messaging widget and all of its features you will require a "Public Key". Public keys are not made available to all merchants. Should you have any questions please speak to your Afterpay account manager.
For Clearpay EU please continue to use our JavaScript Library.
The Afterpay Dynamic Messaging widget allows you to display the standard Afterpay messaging together with Afterpay 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
- 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>
- Initialise the widget by adding the following code into the
<body>of any page you wish to display Afterpay 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 Afterpay payment option.
<div id="afterpay-messaging-widget"></div>
- 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-AU",
// 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 Afterpay
// team
publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
attributes: {
currency: "AUD",
amount: "300",
promoRenderStyle:"promo-with-get-and-payment",
}
});
}
</script>
- 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 Afterpay messaging widget
To replace an existing Afterpay messaging widget with the dynamic widget, follow these steps:
- Add the following code to the
<head>element of your web pages:
<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
- In your web page HTML, find and copy the
afterpay placementelement. It should look something like this:
<afterpay-placement
data-amount="300"
data-locale="en_AU"
data-currency="AUD">
data-...
</afterpay-placement>
- 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.
- Copy the code in the New placement javascript field.
- 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>
- Initialise the widget by adding the following code into the
<body>of any page you wish to display Afterpay 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 Afterpay payment option.
<div id="afterpay-messaging-widget"></div>
- Search for and delete the following code snippet:
<script src="https://js.afterpay.com/afterpay-1.x.js" data-analytics-enabled async></script>
- 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_AU"
data-currency="AUD">
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 Afterpay public key, for example 6e757026-0fcd-4fdc-a858-13017c8f584f | |
| promoRenderStyle | string, optional | promo-onlypromo-or-emptypromo-and-payments-or-emptypromo-and-paymentspromo-with-get-and-payments-or-emptypromo-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 Afterpay 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 Afterpay 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.
Here is a full example of a font face definition.
new AfterPay.Widgets.Placement({
target: "#afterpay-messaging-widget",
locale: "en-AU",
context: "PRODUCT_PAGE",
publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
attributes: {
currency: "AUD",
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-AU",
context: "PRODUCT_PAGE",
publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
attributes: {
currency: "AUD",
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-AU",
context: "PRODUCT_PAGE",
publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
attributes: {
currency: "AUD",
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-AU",
context: "PRODUCT_PAGE",
publicKey: "6e757026-0fcd-4fdc-a858-13017c8f584f",
attributes: {
currency: "AUD",
amount: "200"
}
});
Valid values for the placementPosition option are the same as the valid position values defined here.
All configuration attributes of the static Afterpay messaging widget are applicable to the dynamic messaging widget, and can be found here.
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.
USA only - Pay Monthly Instalment messaging
If you are a merchant based in the USA and have a direct integration to Afterpay, you can offer Pay Monthly.
Merchants who have consumer lending (Pay Monthly) enabled can display specific Product Detail Page (PDP) and shopping cart messaging in the existing widget.
What is Pay Monthly?
Pay Monthly is a monthly payment product is a long-term, instalment-based lending option. It gives your customers more flexible ways to pay for high-value orders greater than $400.
How does Pay Monthly work in practice? Messaging appears when the cart or item price is greater than or equal to $400. It is displayed up to the data-max value that is returned. See the screenshots below:
Your customer clicks the afterpay button on the shopping cart message.
Two monthly payment options appear to the customer, who can select the option they want.
To add Pay Monthly, do the following:
- Access the iframe widget.
- Add
aprLoansAvailable:"true"to theattributesobject.
A full code example is below. The aprLoansAvailable attribute is below the amount attribute, and is set to "true".
<!doctype html>
<html>
<head>
<script src="https://portal.afterpay.com/afterpay.js" async onload="createMessaging()"></script>
<script>
function createMessaging () {
new AfterPay.Widgets.Placement({
target: "#afterpay-messaging-widget",
locale: "en-US",
context: "PRODUCT_PAGE",
publicKey: "00000000-0000-4000-0000-000000000000",
attributes: {
locale: "en_US",
currency: "USD",
amount: "420",
aprLoansAvailable: "true",
}
});
}
</script>
</head>
<body>
<div id="afterpay-messaging-widget"></div>
</body>
</html>
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-US",
context: "CART",
publicKey: "dollar-off-promotion",
attributes: {
amount: "300"
}
});
}
</script>
Updated 5 months ago