Iframes in Apps

You can embed websites in your apps with iframes. The Apps framework provides a set of APIs that allow you to post and receive messages from both your website and your app.

Getting Started

Suppose you want to embed the website "https://dashboard.myapp.com" in a Zendesk app. To embed the site, make the following changes to your website and your app.

Website

Start by adding the following code to your website:

<script type="text/javascript" src="https://assets.zendesk.com/apps/sdk/1.0/zaf_sdk.js"></script>
<script>
  var app = window.ZAFClient.init();

  app.postMessage('hello', { foo: true }); // post the message 'hello' to the Zendesk app

  // listen to the 'app.registered' event, which is fired by the framework once the iframe is registered with the app
  app.on('app.registered', function(data) {
    // go nuts
  });

  app.on('helloIframe', function(data) { // listen to the 'helloIframe' message sent from the app
    if (data.bar) {
      // app says hello
    }
  });
</script>

The code imports the Zendesk App Framework (ZAF) SDK. The ZAF SDK is an open-source JavaScript library that simplifies cross-frame communication between an external website and the Zendesk app containing it. You can view and contribute to the source code on GitHub.

The src attribute in the <script> element must point to a copy of zaf_sdk.js or the minified version zaf_sdk.min.js. To benefit from automatic updates and caching, we recommend you always link to our CDN rather than including your own copy.

After importing the SDK, you call ZAFClient.init(), which returns a ZAF SDK client object. The client allows you to post and receive framework events on your external website. See the Client Object reference below.

App

Switch to your app and use the iframe template helper to load the website in a template. Example:

my_template.hdbs
{{iframe "https://dashboard.myapp.com"}}

As soon as you switch to the template, your app can start receiving iframe events and posting messages back to the iframe. Example:

app.js
events: {
  'app.created':  'init',
  'iframe.hello': 'handleHello'
},

init: function() {
  this.switchTo('my_template');
},

handleHello: function(data) {
  if (data.foo) {
    this.postMessage('helloIframe', { bar: true });
  }
}

To learn more about iframe events and the postMessage API, see the Events reference.

ZAFClient API

When you include the ZAF SDK on your website, you get access to the ZAFClient object.

ZAFClient.init([callback(context)])

Returns a client object.

Arguments
  • callback(context) (optional) a function called as soon as communication with the Zendesk app is established. The callback receives a context object with data related to the Zendesk app, including currentAccount, currentUser, and location

Example:

var client = ZAFClient.init(function(context) {
  var currentUser = context.currentUser;
  console.log('Hi ' + currentUser.name);
});

Client Object

client.postMessage(name, [data])

Allows you to send message events to the Zendesk app.

Arguments
  • name the name of the message event. This determines the name of the iframe event your app will receive. For example, if you set this to 'hello', your app will receive the event 'iframe.hello'
  • data (optional) a JSON object with any data that you want to pass along with the event
var client = ZAFClient.init();
client.postMessage('hello', { awesome: true });
client.on(name, handler, [context])

Allows you to add handlers to a framework event. You can add as many handler as you wish. They will be executed in the order they were added.

Arguments
  • name the name of the framework event you want to listen to. This can be framework, request, or custom events. Your iframe can listen to any events your app receives, apart from DOM events. You don't need to register these events in the app first
  • handler a function to be called when this event fires. You can expect to receive the same event object your app would receive, parsed as JSON
  • context (optional) the value of this within your handler
var client = ZAFClient.init();
client.on('app.registered', function(e) {
  // go nuts
});

Note: As soon as communication with the Zendesk app is established, the SDK triggers an app.registered event. You can add as many handlers to app.registered as you like. They're called immediately after the init callback.

client.off(name, handler)

Allows you to remove a handler for a framework event.

Arguments
  • name the name of the event
  • handler the function you attached earlier with on
var client = ZAFClient.init();

client.on('app.registered', function appRegistered(e) {
  // do stuff then remove the handler
  client.off('app.registered', appRegistered);
});
client.has(name, handler)

Returns whether or not an event has the specified handler attached to it.

Arguments
  • name the name of the event
  • handler the handler you want to test
var client = ZAFClient.init();

client.on('app.registered', function appRegistered(e) {
  // do stuff
});

client.has('app.registered', appRegistered); // true
client.has('app.activated', appRegistered); // false
client.trigger(name, [data])

Triggers the specified event on the client.

Arguments
  • name the name of the event you want to trigger
  • data (optional) data you want to pass to the handler
var client = ZAFClient.init();

client.on('activation', function() {
  console.log('activating!')
});

client.trigger('activation') // activating!
client.request(options)

Dispatch requests via the Zendesk app.

Arguments
  • options the url of the request or an options object containing a url key/value
Returns

A Promises/A+ conformant promise object.

var client = ZAFClient.init();

client.request('/api/v2/tickets.json').then(
  function(tickets) {
    console.log(tickets);
  },
  function(response) {
    console.error(response.responseText);
  }
);