Using postMessage to control an iframe

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.

Consent event: mm:referrer:consent

This event is triggered when a referrer clicks on the CTA to confirm registration in the program.

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 program.

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.