README.md

Build status

Branch	Status
master
production

emarsys-integration-js

Emarsys Integration JS (SIJS) is an API providing methods of communication between Emarsys and integrated services running in an iframe. One can send post messages out of the iframe and SIJS will handle those requests if there is a handler for.

General message format

{
  "event": "handler",
  "data": {
    "some_key": "data"
   },
  "source": {
    "integration_id": "some_integration",
    "integration_instance_id": "iframe's random id"
  }
}

Fields

Field	Role	Mandatory
event	Name of the handler to pass the message to.	YES
some_key	Arbitrary data the handler needs to work properly.
source	This is a signature marking where the message came from. Every integration has an ID (eg. content-editor) and every integration iframe instance has an instance ID (a sufficiently large random number, actually). Though not all message handlers do rely on source, it is best to always include it in your message.	MIXED

Message handlers available

Alert

This handler will render a sticky e-alert box on top of the page and remove it after a timeout has elapsed.

Message format

{
  "event": "alert",
  "data": {
    "text": "Error saving content",
    "icon": "circle-exclamation",
    "className": "e-alert-danger",
    "timeout": 3000
  }
}

Fields

Field	Role	Mandatory	Default
text	Alert message.	YES
icon	Icon class of the icon to be rendered on the left side of the alert. Eg. 'check' for a check mark or 'exclamation-circle' for an exclamation mark in a circle.	NO
className	Alert sub-class to use when rendering the alert. Eg. 'e-alert-success' for a green bar, 'e-alert-danger' for a red one.	NO
timeout	Amount of time after the alert will fade out and get removed from the DOM, in milliseconds.	NO	5000

Confirm

This handler will open a confirm dialog with the content given.

Message format

{
  "event": "enable_button",
  "data": {
    "title": "Are you sure you want to navigate away?",
    "body": "You have unsaved changes you will lose if navigating away.",
    "ok": "Yes I am",
    "cancel": "No, I'm not"
  }
}

Options

Field	Role	Mandatory	Default
title: String	Title of the confirm dialog.	YES
body: String	Body text of the confirm dialog.	NO
cancel: String	Text of Cancel button.	YES
ok: String	Text of OK button.	YES

EnableButton

This handler will remove the class e-btn-disabled from a selection of DOM elements.

Message format

{
  "event": "enable_button",
  "data": {
    "selector": "#foo-id"
  }
}

Fields

Field	Role	Mandatory
selector	jQuery selector.	YES

Modal

This handler will open a modal dialog with content provided by either Emarsys or your service rendered in an iframe inside the modal. It will generate a new integration instance ID for the iframe and glue integration_id, integration_instance_id and opener_integration_instance_id to the iframe URL.

Message format

{
  "event": "modal",
  "data": {
    "src": "some-url-in-your-service",
    "width": 500,
    "height": 200,
  },
  "source": {
    "integration_id": "some_integration",
    "integration_instance_id": "12345"
  }
}

Fields

Field	Role	Mandatory	Default
src	An URL where the markup of the modal content can be found.	YES
width	Width of the iframe we'll include in the modal.	NO	650
height	Height of the iframe we'll include in the modal.	NO	500
source.integration_id	ID of the integration the message is coming from.	NO
source.integration_instance_id	Random instance ID of the integration the message is coming from.	YES

Iframe URL query params auto-added

Param name	Role
integration_id	Integration ID.
integration_instance_id	The new auto-generated instance ID.
opener_integration_instance_id	Instance ID of the integration the modal was opened by.

Modal:close

This handler will remove any e-modal elements from the DOM.

Message format

{
  "event": "modal:close"
}

Navigate

This handler will navigate the browser's main window to a prespecified URL. Target URLs are built using data passed in the message. Session ID is provided by the handler if needed.

Message format

{
  "event": "navigate",
  "data": {
    "target": "some/prespecified/path",
    "params": {
      "foo": "foo_indeed"
    }
  }
}

Fields

Field	Role	Mandatory
target	The prespecified target you would like to head to.	YES
params.foo	The general param the actual target needs.	MIXED

Targets available

Target	Action	Params
email_campaigns/list	Will head to the campaign list.
email_campaigns/edit	Will open the editor with the campaign set.	campaign_id
email_campaigns/copy	Will open the editor with a new copied campaign.	campaign_id
email_analysis/list	Will head to reporting.
email_analysis/details	Will head to reporting details of a campaign.	campaign_id, launch_id
administrators/profile	Administrator profile page	admin_id
administrators/list	Administrator list page
administrators/locked_out	Login page with locked out error message
program/create	AC program creation
trendsreporting/trends	Trend reporting page

Proxy

This handler will forward a message to another integration iframe.

Message format

{
  "event": "proxy",
  "data": {
    "event": "service-event",
    "envelope": {
      "some_key": "data"
    },
    "integrationInstanceId": "9876"
  }
}

Fields

Field	Role	Mandatory
envelope	The message passed to the recipient iframe.	NO
integrationInstanceId	The random ID of the integration you would like to send the message to.	YES

Refresh

This handler will reload the actual browser window.

Message format

{
  "event": "refresh"
}

Resize

This handler will resize the iframe the message came from.

Message format

{
  "event": "resize",
  "data": {
    "height": 100,
  },
  "source": {
    "integration_id": "some_integration",
    "integration_instance_id": "12345"
  }
}

Fields

Field	Role	Mandatory
height	The iframe's desired height.	YES
source.integration_id	ID of the integration the message is coming from.	NO
source.integration_instance_id	Random instance ID of the integration the message is coming from.	YES

Track

This handler will call Google Analytics API if available with the given options.

Message format

{
  "event": "track",
  "data": {
    "eventCategory": "some_category",
    "eventAction": "some_action",
    "eventLabel": "some_label",
    "hitType": "event"
  }
}

Unload:init

This handler will set up click handler for <a> elements, popping a navigation confirm dialog when clicked. It makes sense to call send this event right after your content gets dirty.

Message format

{
  "event": "unload:init",
  "data": {
    "selector": "#menu",
    "confirm": {
      "title": "Are you sure you want to navigate away?",
      "body": "You have unsaved changes you will lose if navigating away.",
      "ok": "Yes I am",
      "cancel": "No, I'm not"
    }
  }
}

Fields

Field	Role	Mandatory	Default
selector: String	Selector for ancestor elements of <a> elements.	YES
confirm: Object	Options for confirm dialog. See dialog.confirm().	NO	Options for a general unload confirm dialog.

Unload:reset

Stopping to watch click events of elements selected by selector. It makes sense to call this method right after your content gets clean (ie. saved).

Message format

{
  "event": "unload:reset",
  "data": {
    "selector": "#menu"
  }
}

Fields

Field	Role	Mandatory
selector: String	Selector for ancestor elements of <a> elements.	YES

Development

If you would like to make local changes, you need to run gulp start. You can reach the resulting code on this local URL then.

Deployment

Code is automatically built and deployed whenever there is a new changeset in following branches:

Changes to branch	Go live on environment
master	staging
production	production

So you can push your changes into the master branch, and Codeship will deploy it to the staging environment. Also you can merge your changes to the master branch, and it will be deployed to production by Codeship:

git checkout production
git pull --rebase
git merge origin master
git push