Building a host page

Article
07/06/2022

To instantiate Office for the web applications, a host must create an HTML page that contains an iframe element within it that's pointing to a particular WOPI action URL. A host page provides benefits, including:

Since the Office for the web application is hosted within a host page, the host page can communicate with the frame easily using PostMessage. This supports a richer integration between the host and Office for the web.
URLs displayed in the user’s browser are host URLs. So, from a user’s perspective, they're interacting with the host, not Office for the web. This also ensures that URLs copied and pasted by users are host URLs, not Office for the web URLs.

The host page is typically simple and must only meet the following requirements:

It must use a form element and POST the access token and access_token_ttl values to the Office for the web iframe for security purposes. Also, it's recommended to post user_id and owner_id values to the iframe. It's a requirement to post user_id and owner_id values for CSPP Plus scenarios.
It must include any JavaScript needed to interact with the Office for the web iframe using PostMessage.
It must manage wd* query string parameters.
It must apply some specific CSS styles to the body element and Office for the web iframe to avoid visual bugs.
It must declare a viewport meta tag to avoid visual and functional problems in mobile browsers.

Host page example

The GitHub repository contains a minimal example host page.

Note

The example host page doesn't illustrate managing wd query string parameters or using PostMessage to interact with the Office for the web application iframe. The following sections refer to these considerations in more detail.

Passing access tokens securely

For security purposes, it's important that access tokens not be passed to the Office for the web iframe as a query string parameter. Doing so would greatly increase the likelihood of token leakage. To avoid this problem, hosts must pass the access token and access_token_ttl values to the Office for the web iframe using a form POST. This technique is illustrated, along with dynamic iframe creation, in code sample one.

Work around browser iframe behaviors

Some browsers exhibit unexpected handling of iframes when using bookmarks or the browser forward and back buttons.

In some cases, the Office for the web iframe is loaded twice in a single navigation, which can cause file locked or access token expired errors for users.

Also, occasionally the iframe isn't recreated at all, which causes the Office for the web application to load with the previous session’s state. This might cause a session to fail for a variety of reasons, including an expired token.

In order to avoid this result, hosts must dynamically create the Office for the web iframe using JavaScript, then dynamically submit it. This technique is shown in the sample host page:

Code sample 1 - Markup from SampleHostPage.html illustrating how to dynamically create the Office for the web iframe and pass access tokens securely

<body>

    <form id="office_form" name="office_form" target="office_frame" action="<OFFICE_ACTION_URL>" method="post">
        <input name="access_token" value="<ACCESS_TOKEN_VALUE>" type="hidden" />
        <input name="access_token_ttl" value="<ACCESS_TOKEN_TTL_VALUE>" type="hidden" />
        <input name="user_id" value="<USER_ID_VALUE>" type="hidden" /> 
        <input name="owner_id" value="<OWNER_ID_VALUE>" type="hidden" />
    </form>

    <span id="frameholder"></span>

    <script type="text/javascript">
        var frameholder = document.getElementById('frameholder');
        var office_frame = document.createElement('iframe');
        office_frame.name = 'office_frame';
        office_frame.id = 'office_frame';

        // The title should be set for accessibility
        office_frame.title = 'Office Frame';

        // This attribute allows true fullscreen mode in slideshow view
        // when using PowerPoint's 'view' action.
        office_frame.setAttribute('allowfullscreen', 'true');

        // The sandbox attribute is needed to allow automatic redirection to the O365 sign-in page in the business user flow
        office_frame.setAttribute('sandbox', 'allow-scripts allow-same-origin allow-forms allow-popups allow-top-navigation allow-popups-to-escape-sandbox');
        frameholder.appendChild(office_frame);

In an actual implementation, the <OFFICE_ONLINE_ACTION_URL>, <ACCESS_TOKEN_VALUE>, and <ACCESS_TOKEN_TTL_VALUE> strings must be replaced with appropriate action URL, access token, and access_token_ttl values.

Pass additional query string parameters

Office for the web sometimes passes additional query string parameters to your host page. These query string parameters are of the form wd*. When you receive these query string parameters on your host page URLs, you must pass them, unchanged, to the Office for the web iframe.

In addition, if the replaceState method from the HTML5 History API is available in the user’s browser, you should remove the following parameters from your host page URL after passing them to the Office for the web iframe:

wdPreviousSession
wdPreviousCorrelation

Other wd* parameters must not be removed from the host page URL.

Host page headers

If the host page headers are not correctly set, some browsers might cache the response, which can result in the host page not properly reloading when the user navigates to it. This can result in errors if the user reloads a cached page after the access token, or access_token_ttl have expired. One way this can happen is by reloading the page using the forward and back buttons. For more information about cache management, see RFC 7234.

To prevent this, at the very least, set the following headers on the host page.

Cache-Control: no-cache, no-store
Expires: -1
Pragma: no-cache

Other headers, such as Date and Vary are useful as well.

Apply appropriate CSS styles

To ensure that the Office for the web applications behave appropriately when displayed through the host page, the host page must do the following:

Apply specific CSS styles to the Office for the web iframe (lines 22-33) and the body element (lines 15-20).
Set a viewport meta tag for mobile browsers (lines 11-12).
Set an appropriate favicon for the page using the favicon URL provided in WOPI discovery.

These requirements are shown in the sample host page:

Code sample 2 - Markup from SampleHostPage.html illustrating appropriate styles and favicons in a host page


<head>
    <meta charset="utf-8">

    <!-- Enable IE Standards mode -->
    <meta http-equiv="x-ua-compatible" content="ie=edge">

    <title></title>
    <meta name="description" content="">
    <meta name="viewport"
        content="width=device-width, initial-scale=1, maximum-scale=1, minimum-scale=1, user-scalable=no">

    <link rel="shortcut icon" href="<OFFICE APPLICATION FAVICON URL>" />

    <style type="text/css">
        body {
            margin: 0;
            padding: 0;
            overflow: hidden;
            -ms-content-zooming: none;
        }

        #office_frame {
            width: 100%;
            height: 100%;
            position: absolute;
            top: 0;
            left: 0;
            right: 0;
            bottom: 0;
            margin: 0;
            border: none;
            display: block;
        }
    </style>
</head>