@plugins.chat/drift-meta-frame
v1.0.1
Published
[](https://badge.fury.io/js/@plugins.chat%2Fdrift-meta-frame)
Downloads
15
Readme
Drift meta frame
View live next.js demo Edit next.js demo on StackBlitz ⚡️ Edit this repo on StackBlitz ⚡️
The Drift chat widget usually requires a small snippet to be pasted on your page that essentially stubs out an API on the window, sets up a q to process any API calls made before it has loaded, and pulls in some small initialization code on the host page.
The initialization code generates two iframes (one for the chat window and one for the controller) and sets up a post message communication layer between the host and those iframes.
In some cases, larger organizations (or individuals) have security policies that have a problem pulling in live code directly on their page and require a different strategy to avoid exposing themselves to non-compliance of those policies.
This package aims to help solve some of those issues. Instead of bootstrapping the widget by pulling full-screen on the host at load-time, this package allows you to set up a single iframe that wraps the drift install (a meta frame) - it works by setting up a full-screen iframe that lets drift behave as if it were loaded directly on the host, but maintains separation and can be loaded into any other domain or source. It uses mouse move event handlers to determine whether or not we should focus on the meta frame or the host and pointer-events: none to allow for pass-through back to host.
Because of the use of pointer-events to achieve this, browser support is limited to those that support it (all modern ones as of today 02/22) see here
Table of contents
Getting Started
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
Installation
To install and set up the library, run:
$ npm install drift-meta-frameor with Yarn:
$ yarn add drift-meta-frameor globally via unpkg
<script src="https://unpkg.com/@plugins.chat/drift-meta-frame" type="text/javascript"></script>Usage
Setting up your host
module
import { initializeHost } from 'drift-meta-frame';
...
initializeHost({
log: false,
frame_url: 'https://mydomain.com/drift'
});global
<html>
<head>
<script src="https://unpkg.com/@plugins.chat/drift-meta-frame" type="text/javascript"></script>
</head>
<body>
<h1>host</h1>
...
<script>
window.driftMetaFrame.initializeHost({ log: true, frame_url: '/frame' });
</script>
</body>
</html>
Setting up your frame
module
import { initializeMetaFrame } from 'drift-meta-frame';
...
initializeMetaFrame({
embed_id: 'your_drift_embed_id'
});global
<html>
<head>
<script src="https://unpkg.com/@plugins.chat/drift-meta-frame" type="text/javascript"></script>
</head>
<body>
<script>
window.driftMetaFrame.initializeMetaFrame({ embed_id: 'your_drift_embed_id' });
</script>
</body>
</html>
API
initializeMetaFrame
initializeMetaFrame({
embed_id: 'your_drift_embed_id'
});Options
| Property | Type | Default value | | -------- | ------ | ------------- | | embed_id | string | '' |
initializeHost
initializeHost({
log: false,
frame_url: 'https://mydomain.com/drift'
});Options
| Property | Type | Default value | | --------- | ------- | ------------- | | log | boolean | false | | frame_url | string | '' |
drift
this export is a utility that passes any call to the drift widget api from host to frame.
This uses the v2 style api which only requires that u pass the method u would like to invoke as the first argument, followed by any arguments to be applied to that method.
only to be used from the host.
drift('showWelcomeMessage');
drift('startInteraction', {
interactionId: interactionIdForEvent,
replaceActiveConversation: false
});updateContext
To maintain the ability for drift to target based on the current session information on the host, we need to pass through that context (window location, etc..). We wet that context initially on init, but in cases where your application may do a thing like routing in the browser or make updates that you would expect Drift targeting needs to be aware of, you can call this function to make sure the frame has the latest.
this is just a convenience utility that wrapps drift('setContext', getContext())
updateContext()updateContext
If you need to adjust the context object manually, you can use this utility to get the baseline and do what you want with it.
const context = {
...getContext(),
...overrides
}
drift('setContext', context)returns ->
{window: {
location: {
hash: window.location.hash,
host: window.location.host,
hostname: window.location.hostname,
href: window.location.href,
origin: window.location.origin,
pathname: window.location.pathname,
port: window.location.port,
protocol: window.location.protocol,
search: window.location.search,
},
navigator: {
language: window.navigator.language,
browserLanguage: window.navigator.browserLanguage,
userAgent: window.navigator.userAgent,
},
innerHeight: window.innerHeight,
innerWidth: window.innerWidth,
},
document: {
title: document.title,
referrer: document.referrer,
}}Options
License
MIT License © Dimitrios Kennedy-Kavouras