Embedding a Pass Template

Show one pass template of your account inside your own web application, so that your users can work with it without an account and without signing in to Passcreator.

This guide shows how the parts fit together. Every parameter of the token endpoints is documented in Embed Tokens.

How It Works

1. Your server creates an embed token with Create an Embed Token. The token names the pass template, the origin of your page, the tabs and actions to offer, the language and, optionally, who your user is.
2. Your page loads the returned embedUrl in an iframe. The URL points to your custom domain and carries the token.
3. The iframe opens the token and starts an embed session in the user's browser. It then tells your page that it is ready.
4. The user works with the template in the tabs and with the actions the token grants, never with more than the user who created the token may do.
5. The session ends at its absolute end, when your page ends it, or when the token is revoked. The iframe tells your page.

Requirements

• The embedded feature must be enabled for your account. Contact support@passcreator.com to enable it.
• A custom domain on the same site as your application. The iframe runs on your account's custom domain, and your page must be on that domain's parent domain or one of its subdomains (custom domain passes.example.com, your application on example.com or app.example.com). Otherwise browsers treat the session of the iframe as a third-party cookie and block it. If your account has no custom domain yet, request a White Label Domain in Passcreator under Subscription › Additional Services.
• HTTPS for the page that embeds the iframe.
• An API key of a user who has every permission the tabs and actions need (see Capabilities). Keep the API key on your server.
• A current browser. The embedded view only opens inside an iframe and relies on the browser telling it so: Chrome and Edge 80 or later, Firefox 90 or later, Safari 16.4 or later. Older browsers see a neutral notice instead of the view.

Quickstart

Step 1: Create the Token on Your Server

Add an endpoint to your backend that creates a token for the signed-in user and returns the embedUrl. Create a new token every time the iframe is rendered; a token can be opened only once and expires after 10 minutes by default. Replace yourApiKeyHere with the API key of the user who creates the tokens and yourTemplateId with the ID of your pass template.

app.post('/embed-token', async (req, res) => {
  const response = await fetch('https://app.passcreator.com/api/v3/embed/token', {
    method: 'POST',
    headers: {
      'Authorization': 'yourApiKeyHere',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      data: {
        templateId: 'yourTemplateId',
        embeddingOrigin: 'https://app.example.com',
        capabilities: {tabs: ['overview', 'passes'], actions: ['createPass', 'updatePass']},
        language: req.user.language,
        metadata: {externalUserId: req.user.id, externalUserName: req.user.name}
      }
    })
  });
  const body = await response.json();
  if (!body.success) {
    return res.status(502).json({error: body.errors[0]});
  }
  res.json({embedUrl: body.data.embedUrl});
});

The same request in cURL, PHP and Python is shown in Create an Embed Token.

Step 2: Load the Iframe

Fetch the URL from your endpoint and set it as the src of the iframe. To open a specific tab first, append &view= with a tab the token grants; any other value opens the overview.

<iframe id="pass-template" title="Pass template" style="width: 100%; height: 800px; border: 0;"></iframe>

<script>
  const iframe = document.getElementById('pass-template');

  async function openEmbed(view) {
    const response = await fetch('/embed-token', {method: 'POST'});
    const {embedUrl} = await response.json();
    iframe.src = view ? embedUrl + '&view=' + encodeURIComponent(view) : embedUrl;
  }

  openEmbed('passes');
</script>

Step 3: Listen to the Iframe

The iframe tells your page when it is ready and when the session has ended. Check where each message comes from before you act on it:

window.addEventListener('message', (event) => {
  // only the iframe you created, on the origin of its embedUrl
  if (event.source !== iframe.contentWindow || event.origin !== new URL(iframe.src).origin) return;
  const message = event.data;
  if (!message || message.source !== 'passcreator-embedded') return;

  if (message.type === 'ready') {
    // the session runs; message.templateId is the opened template
  } else if (message.type === 'sessionEnded') {
    // message.reason is 'sessionExpired' or 'sessionEnded'
  }
});

Messages Between the Iframe and Your Page

The iframe and your page talk through window.postMessage. Every message is an object with a source marker and a type.

From the Iframe to Your Page

The iframe sends its messages only to the embeddingOrigin of the token, with source set to passcreator-embedded.

From Your Page to the Iframe

Send your messages to the iframe's window, with the origin of the embedUrl as target and source set to passcreator-embedded-host. The iframe ignores messages that do not come from its parent window on the embeddingOrigin, and every message it does not know.

const embedOrigin = new URL(iframe.src).origin;

// switch to the passes tab
iframe.contentWindow.postMessage({source: 'passcreator-embedded-host', type: 'navigate', tab: 'passes'}, embedOrigin);

// end the session, e.g. when your user signs out
iframe.contentWindow.postMessage({source: 'passcreator-embedded-host', type: 'end'}, embedOrigin);

Sessions

• One token, one session. Opening the token starts the embed session; the token cannot be opened again. Reloading the iframe continues the running session.
• Absolute length. The session lasts sessionLifetime seconds from the moment the token was opened, 8 hours by default. There is no timeout for inactivity.
• Ended early when the token is revoked, the embedded feature is switched off for your account, the API key that created the token expires or is disabled, the user who created the token is deactivated, or the template is archived. The session ends on its next request and the iframe sends sessionEnded.
• After the end the iframe shows a neutral notice that asks the user to open the view again from your application. It offers no reload, because the token in the URL is used up. React to sessionEnded instead: create a new token on your server and set the iframe's src to the new embedUrl. Only after an unexpected error, while the session still runs, does the notice offer a reload.
• One embed per browser. All embedded views in a browser share one session. A new token opened in the same browser, in another tab or for another template, replaces the running session: the older iframe ends with sessionEnded as soon as it next checks its session, at the latest after ten minutes. Showing two embedded views in one browser at the same time is not supported. Do not reload the older iframe with its used token: that ends the newer session as well. Create a new token instead.

Appearance and Language

• The view uses the theme of your account if one is set up.
• Texts and date and number formats follow the language of the token. Always send it; without it the texts follow the browser's language while dates and numbers fall back to English formats.

Security

• Only your page can show the view. The view can only be framed by a page on the token's embeddingOrigin. Opening the embedUrl directly in a browser tab shows a neutral notice instead.
• Check every message. Act only on messages from your iframe on the origin of its embedUrl, as in the example above.
• Grant only what is needed. The view offers exactly the tabs and actions of the token, never more than the user who created the token may do. The permissions are checked when the token is created; to take rights back at once, revoke the tokens with Revoke an Embed Token.
• Metadata is attribution only. externalUserId, externalUserName and reference are stored as your page sent them and never decide what the user may do.

Limitations

• The template's validation features are not available in the embedded view.
• Only one embedded view per browser at a time (see Sessions).
• Supported browsers: Chrome and Edge 80 or later, Firefox 90 or later, Safari 16.4 or later.