Iframe Interactions

Overview

A partner's menu page displayed in an Iframe(the iframe page) often has rich UI interactions such as dropdown, accordion or popup. These interactions oftentimes require communication and data passing between the iframe page and parent page in order to display things correctly. This document provides the guidelines of cross-domain communication for different interactions.

For any style or developer guidelines, please make sure you review this guide.

Requirements

The method used for cross-domain communication is window.postMessage. This method is supported by FF3+, IE8+, Chrome, Safari4+, Opera9.5+ (http://caniuse.com/x-doc-messaging). In the browsers that don't support postMessage, we will display a blank page with a message to upgrade the browsers.

Yelp uses the setHeight event to determine when to dismiss the webview's loading spinner. The partner is responsible for making sure that the iFrame contents are interactable before calling setHeight.

Frame URL and Content

This is the URL that Yelp will specify in the iframe to initiate the ordering flow on the partner's site.

It must be HTTPS. The iframe page must use HTTPS assets as well or browsers will raise mixed content warnings.

A yelp_site query parameter will be added to iframe URLs to mitigate the risk of mixed experiences between a menu page and its host.

yelp_site will be one of www or m

yelp_locale is described below

Currently, devices families supported by Yelp's mobile site are:

• iPhone
• iPod
• FirefoxOS
• Android (tablet and phones)

Note the exclusion of iPads, Windows phone and Blackberry devices for instance. Those device will be served Yelp's desktop site (www.yelp.com) and should get a desktop menu page to avoid mixed experiences.

URL template

https://<partner_domain_path>/<partner_business_id>/?opportunity_token=<oppotunity_token>&yelp_site=m&yelp_locale=en_US

The partner_domain_path shall be pre-registered with Yelp.

Request Params

Sending Messages To Yelp

To send a message to its parent window, a partner's iframe must use the postMessage API:

window.top.postMessage(message, targetOrigin)

message param

• Must contain information about the event type (e.g., setHeight, scrollTop. See table below for details)
• May contain more properties, depending on the event type
• Must be a JSON encoded string

targetOrigin param

The value of this param must be computed by partners, based on two GET params added by Yelp to iframe URLs, yelp_site and yelp_locale

Partners must validate GET params to prevent against potential targetOrigin hijacking.

• yelp_site should be one of (www, m). If no valid yelp_site is provided, it is safe to throw an error.
• yelp_locale should be a valid yelp locale. If no valid yelp_locale is provided, it is safe to throw an error.

Here's a table showing mappings between different values of yelp_site, yelp_locale and targetOrigin.

Concrete example

Makes the parent Yelp page scroll to a vertical offset of 64px:
(inside https://<partner_domain_path>/menu/123?opportunity_token=&yelp_locale=en_US&yelp_site=www)

window.top.postMessage(
    '{"eventType": "scrollTop", "offset": "64"}',
    'https://www.yelp.com'
);

Same example, from the French mobile site:

(inside https://<partner_domain_path>/menu/123?opportunity_token=&yelp_locale=fr_FR&yelp_site=m)

window.top.postMessage(
    '{"eventType": "scrollTop", "offset": "64"}',
    'https://m.yelp.fr'
);

Mobile vs. Desktop context

A yelp_site URL param (values: www or m) is added by Yelp to iframe URLs. This indicates to partners if their pages are loaded in a desktop or mobile context.

Partners may use this to customize their iframe based on the current context.

Testing

You can test your iframe and these API's once you've activated your test business widget.