PostMessage Iframe Events

The Mention Me journey is often presented inside an iframe (embedded into your website) or within a “WebView” inside a mobile application. When a user interacts with the Mention Me journey inside the iframe, it can be useful to update your own site - e.g. tracking events in your analytics. If you’re using our EntryPoint API to show the Mention Me experience inside a “WebView”, it is also important for Mention Me to be able to tell you when a user has requested to close a popup. Using the postMessage API, we can send you a message when a user completes certain actions. Common examples include:

Track when a user actively enrols into the referrer journey
For clients using the EntryPoint, close the iframe when a user clicks close.
Update your checkout with a coupon code when a referee is rewarded a coupon.

This solution requires no tags or 3rd party JS dependencies on Mention Me. Here’s some example code you can install in your website (commonly referred to as the “parent”):

window.addEventListener('message', (event) => {
    let { data = {} } = event;
    // For security, filter for accepted origins here

    // Handle IE browser support
    if (typeof data === 'string') {
        try {
            data = window.JSON.parse(data);
        } catch (error) {
            data = {};
            // Handle errors if desired.
        }
    }

    switch (data.action) {
        case 'mm:referee:close':
        case 'mm:referrer:close':
        case 'mm:referrer-share:close':
            // This will be triggered whenever the IFRAME needs to be closed
            // (by the user or by them reaching the end of the flow in any case)
            // You should close the IFRAME here
            break;
        case 'mm:referrer:consent':
            // A referrer has clicked the CTA in the referrer journey to confirm they wish
            // to be actively enrolled in the program.
            break;
        case 'mm:referee:fulfilled':
            // This will be triggered whenever the user gets given a coupon at the
            // end of the happy path and you should apply the coupon if present
            // and possible
            break;
        default:
        // Future post message events may be provided.
        // They can be ignored for now.
    }

});

Close event: `mm:*:close`

The close event is triggered when a customer clicks the close button inside an iframe hosted by Mention Me. In the Mention Me Javascript tags, the Mention Me javascript will automatically handle closing the iframe. If you’re using the EntryPoint API to render your own iframe or web page inside a mobile app, you can use this close event to trigger your code to close the iframe/web page and return the user to the page. An example close event which can be used to detect that the user wishes to close the iframe is below:

{
    "action": "mm:referee:close",
    "sourceName": "Referee1577983405347"
}

Note:sourceName is our own internal validation mechanism, you can ignore this. This event is triggered when a referrer clicks on the CTA to confirm registration in the programme. In the case of a journey where the users details are pre-populated (e.g. post purchase), this event will fire when the user clicks on the CTA. In the case of a journey where the users details are not pre-populated (e.g. a landing page), this event will fire when the user has entered their details to register with the programme.

Referee fulfil event: `mm:referee:fulfilled`

We fire the mm:referee:fulfilled event when the referee gets given a coupon (or told they still have a valid coupon) - before they click the final CTA or close icon. So you should be able to apply the coupon as soon as there is one. Because of this, when the user finishes the flow (by clicking either close or the final CTA to “continue shopping”) you will have already handled the coupon and so we will fire the mm:referee:close event. Note for clients with “after purchase” rewards, since there is no coupon produced by the journey, the only event that will be fired is the mm:referee:close one. The payload would look something like this in each case:

{
    "action": "mm:referee:fulfilled",
    "referee": {
        "email": "[email protected]"
    },
    "coupon": {
        "couponCode": "REFEREE123",
        "securityCode": "CODE456",
        "expiryDate": "2021-01-02"
    },
    "message": "Here is 20% off your first order thanks to John",
    "sourceName": "Referee1577983405347"
}

Note:sourceName is our own internal validation mechanism, you can ignore this. The elements of the payload are to be used how you see fit to optimise conversion in the referee journey - for example telling them how long they have to spend the coupon or using the content to explain why they have received this coupon and encourage conversion.

Click action event: `clickAction`

For Entry Point API journeys embedded in an iframe on a checkout (or any other page you don’t want the customer to navigate away from), the referee experience can send a clickAction message so you can close the iframe and keep the customer where they are, instead of following the CTA link. Mention Me sends this message when the customer clicks the final CTA in the journey:

{
    "choice": "clickAction",
    "clickAction": "https://www.example.com/",
    "clickType": "redirect",
    "sourceName": "",
    "suffix": "Referee"
}

clickAction - the URL the CTA would normally redirect the customer to.
suffix - "Referee" or "Referrer" depending on which journey the message was sent from.

Listen for this event in the parent page and close the iframe instead of allowing the redirect:

window.addEventListener('message', function (e) {
    var d = e.data;
    if (d && d.choice === 'clickAction') {
        closeIframe(); // close the iframe and keep the customer on the current page
    }
});

Replace closeIframe() with your own function that hides or removes the Mention Me iframe from the DOM. This is the recommended pattern when the Entry Point API journey is embedded directly in your checkout flow.

FAQ

View frequently asked questions.

Getting Started

Auth API

Merchant API

Entrypoint API

Consumer API

Webhooks

Close event: `mm:*:close`

Referee fulfil event: `mm:referee:fulfilled`

Click action event: `clickAction`

FAQ

​Close event: mm:*:close

​Consent event: mm:referrer:consent

​Referee fulfil event: mm:referee:fulfilled

​Click action event: clickAction

FAQ

Close event: `mm:*:close`

Consent event: `mm:referrer:consent`

Referee fulfil event: `mm:referee:fulfilled`

Click action event: `clickAction`