Embed API: Communicate Between Your Website And Its Interactive Experiences

When you embed a project on your website, Dot.vu provides a client side API that enables you to communicate between your website and the embedded Dot.vu experience. To enable this, you must use the Dot Embed Library Add-On in your experience.

There are several options for sending and retrieving information:

• Initialize the Dot.vu page with URL Data
• Subscribe to triggered events
• Get the value of a session data field
• Set the value of a session data field
• Run a Custom Action

All possible use cases of the Dot Embed Library are exemplified in the code below. Note that this is only available for the event type “projectLoad”. That is the default event you obtain when copying a project tag from your project’s “Put on Website” editor setting.

Once the project has loaded and is ready, the optional callback in the details property will be called, with a possible error as first argument, and the Page instance as second argument, on success.

Once you have access to the Page instance, you can start to use it to handle events, actions and data fields.

window["dotVu"]({
  eventType: "projectLoad",
  accountId: 155,
  details: {
    options: {...},
    config: {
      ...,
      // optional url data to send to the page (requires URL Data Add-On)
      urlData: {
        customerId: '123',
      }
    },
    callback: function (error, page) {
      if (error) {
        // handle loading error

      } else if (page) {
        var events = page.events
        var actions = page.actions
        var datafields = page.datafields

        // Subscribe to triggered events.
        events.subscribe('new-lead', function (lead) {
          console.log(lead)
        })

        // Get a session data field value
        datafields.get('counter').then(function (value) {
          console.log(value)
        })

        // Set a session data field value
        datafields.set('counter', 10)

        // Run a custom action
        actions.run('showButton')
      }
    },
  },
});

Did you know? You can use the callback parameter to handle loading errors, so you can inform and/or redirect your users for continuous engagement in case of loading errors.

Legacy API

If you are using the Legacy API please see the example below. If you are unsure if you are using the Legacy API or not, look for window.dotEmbed on your Dot.vu embedding snippet.

// Dot.vu page's config
var config = {
  dotId: 155,
  pageId: '60ab77612d249b5070590e07',
  loading: 'on',
  height: 'auto',
  width: '100%',

  // optional url data to send to the page (requires URL Data Add-On)
  urlData: {
    customerId: '123',
  },
}

window.dotEmbed.load(el, config, function (page) {
  var events = page.events
  var actions = page.actions
  var datafields = page.datafields

  // Subscribe to triggered events.
  events.subscribe('new-lead', function (lead) {
    console.log(lead)
  })

  // Get a session data field value
  datafields.get('counter').then(function (value) {
    console.log(value)
  })

  // Set a session data field value
  datafields.set('counter', 10)

  // Run a custom action
  actions.run('showButton')
})

Embedding Multiple Projects?

If you are using the Site Tag or embedding multiple projects, you can subscribe to events triggered by the Embed Library Add-On from all projects you embed on your website. These include all projects loaded via the Site Tag or the Project Tag.

This is very useful in cases where you want to handle events in a general way regardless of the project. Typical uses cases include:

• Send events to Google Analytics or Google Tag Manager
• Add to Cart functionality

To define a general handler for specific embed library events you can change the “init” event of the DotJS Embed Library to add a “onReady” property callback that is called with the DotJSContext, which you can use to subscribe to specific events triggered by the Embed Library Addon.

window["dotVu"]({
  eventType: "init",
  accountId: "123",
  details: {
    onReady: function (dotContext) {
      // Replace 'my-event-name' with the event name you want to subscribe to.
      dotContext.subscribe("embed-library-event:my-event-name", function (event) {
        console.log(event.data)
        console.log(event.pageId)
      });
    },
  },
});

By replacing the “init” event on the Site Tag you are able to define a general handler for all events triggered from all your Dot.vu projects embedded on your website.