{"_id":"58dab3017086990f008f9d11","__v":2,"parentDoc":null,"project":"5588b8a2f6c18d0d005bba03","user":"5588b847f6c18d0d005bba01","version":{"_id":"5588b8a2f6c18d0d005bba06","project":"5588b8a2f6c18d0d005bba03","__v":16,"createdAt":"2015-06-23T01:38:42.696Z","releaseDate":"2015-06-23T01:38:42.696Z","categories":["5588b8a3f6c18d0d005bba07","5588e9689cfea70d00371df3","5588f5921163180d00b64704","561598b121e9110d0078025a","5616f1c9d170d00d00189306","5616f5c3a410c90d00c6121e","561803dcf8c9632100ac7592","563667280441020d0000e9eb","5642570d9417b40d00c0fcd3","57bf5f02efe0050e00d50bd5","57f53fb368a53b2000e03f0f","57f55187440418170086325a","582e3afa72fd270f0006926d","5841faa973967b0f004b4a2b","58db348aa32c8419002433bb","5a31c9409a6f2000125c079f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"58db348aa32c8419002433bb","version":"5588b8a2f6c18d0d005bba06","__v":0,"project":"5588b8a2f6c18d0d005bba03","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-03-29T04:14:02.294Z","from_sync":false,"order":2,"slug":"sidebar-integrations","title":"Build a Mixmax Sidebar"},"updates":["593036b63d2a84000f3fbb9d","593b71ab67293f0019407fed"],"next":{"pages":[],"description":""},"createdAt":"2017-03-28T19:01:21.193Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The Mixmax sidebar is present in Gmail and Inbox (but soon all over the web!) with the [Mixmax extension](https://chrome.google.com/webstore/detail/mixmax-email-tracking-tem/ocpljaamllnldhepankaeljmeeeghnid?hl=en) installed. Its primary purpose is to show contextual information about a particular email address (though this will change in the future as more APIs are added). In the top of the sidebar it shows the selected contact, and then beneath it lists tabs of \"sidebar integrations\" that you have installed. A sidebar integration is a standalone website that is loaded inside an iframe that can respond to a new contact being \"selected\" via a Javascript API.\n\nThrough the Mixmax Sidebar SDK discussed here, you can add your own sidebar to Mixmax. This makes it possible to extend Mixmax with your own tools.\n\nMixmax comes with two built-in sidebar integrations:\n\n* Contact profiles - lists contact profiles for the selected contact\n* Salesforce ([Growth](https://mixmax.com/pricing) or above only) - syncs the contact to Salesforce\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/73af028-Screen_Shot_2017-03-28_at_3.52.45_PM.png\",\n        \"Screen Shot 2017-03-28 at 3.52.45 PM.png\",\n        271,\n        469,\n        \"#3c577e\"\n      ],\n      \"caption\": \"The Mixmax sidebar in Gmail\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Adding your sidebar integration to Mixmax\"\n}\n[/block]\nYou can add a sidebar integration to Mixmax in your [developer settings dashboard](https://app.mixmax.com/dashboard/settings/developer). You will need [Growth](https://mixmax.com/pricing) or above for access—email support:::at:::mixmax.com for a free trial.\n\nThis will add the sidebar integration for your personal use. You may also share it with individual users, by email, or with your Mixmax team(s). When you're ready to release your integration to all Mixmax users, email us at support@mixmax.com with your request.\n\n## Parameters\n\nTo add your sidebar integration, you will need a few pieces of information:\n\n### Name\n\nThe name of your integration to show up in developer settings.\n\n### URL\n\nThe URL of your integration. The webpage at this URL should use the Sidebar SDK, as described in the following sections, to communicate with the Mixmax extension.\n\n### Tab icon\n\nThere are two ways to specify the icon used to represent your integration's tab in the Mixmax extension:\n\n* you can provide the URL of an image, or\n* you can provide the name of a [Font Awesome](http://fontawesome.io/icons/) icon such as \"info-circle\" _and_ a color, specified as a hex value, such as \"#8a8a9e\".\n\nYou must specify either an image _or_ both the name _and_ color.\n[block:api-header]\n{\n  \"title\": \"Loading the Sidebar SDK\"\n}\n[/block]\nInclude the following line of Javascript in your website:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script defer src=\\\"https://sdk.mixmax.com/v1.5.2/sidebar.umd.min.js\\\"></script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nThe script will create the global object `Mixmax.sidebar`. See below for its use.\n\nIf you're using a JavaScript bundler like [Rollup](https://rollupjs.org/) or [Webpack](https://webpack.github.io/), instead of loading the SDK using a script tag, you can import the SDK from npm like\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"const Mixmax = require('@mixmaxhq/sdk');\\n\\nMixmax.sidebar.on('contactSelected', (contact) => console.log(contact));\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nIf your bundler is capable of importing ES6 modules and understands `pkg.module`, you can import the SDK like\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import { sidebar } from '@mixmaxhq/sdk';\\nsidebar.on('contactSelected', (contact) => console.log(contact));\\n\\n// If your bundler understands [`pkg.browser`](https://github.com/defunctzombie/package-browser-field-spec)\\n// like Rollup does when using rollup-plugin-node-resolve with\\n// [`browser: true`](https://github.com/rollup/rollup-plugin-node-resolve#usage),\\n// you can import the Sidebar SDK directly. This is not only a more concise\\n// import but may actually lead to bundling less JS due to \\n// https://github.com/rollup/rollup/wiki/Troubleshooting#tree-shaking-doesnt-seem-to-be-working\\nimport sidebar from '@mixmaxhq/sdk/sidebar';\\nsidebar.on('contactSelected', (contact) => console.log(contact));\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Using the Sidebar SDK\"\n}\n[/block]\nOnce you have loaded the `sidebar` object, you can use it to listen for events from the Mixmax extension telling you when and how to update your sidebar integration. The `sidebar` object is an [`eventemitter3`](https://www.npmjs.com/package/eventemitter3#usage) instance, so you register event listeners like\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"sidebar.on('contactSelected', (contact) => console.log(contact));\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## Events\n\nThe events that the object emits are:\n\n### Event: 'contactSelected'\n\nArguments:\n\n* _contact_ `<Object>` A contact that the user just selected, for instance by hovering over an email address in Gmail. This object will have the following properties:\n  * `email` `<String>` The email address of the contact.\n  * `fullName` `<String>` (Optional) The full name of the contact, if available.\n  * `image` `<String>` (Optional) The URL of an image for the contact.\n\nWhen you receive this event, you should populate your integration with information related to the contact. For instance, if your integration represented a task manager, your integration might display a list of tasks assigned to this contact.\n\n### Event: 'beforeContactSelected'\n\nArguments:\n\n* _event_ `<Event>`\n\nListening to this event is optional. You should listen to this event if you wish to prevent the sidebar from selecting a new contact, perhaps because the user has not finished editing information in your integration related to the current contact. Calling `event.preventDefault()` will prevent the sidebar from updating to show the new contact. (The user will then have to re-select that contact at some later point, at which time this event will be emitted again.)\n\n### Event: 'clear'\n\nNo arguments.\n\nWhen you receive this event, you should clear your integration of the information it is currently displaying. This event is not currently emitted but may be in the future.","excerpt":"","slug":"sidebars","type":"basic","title":"Introduction: Sidebar SDK"}

Introduction: Sidebar SDK


The Mixmax sidebar is present in Gmail and Inbox (but soon all over the web!) with the [Mixmax extension](https://chrome.google.com/webstore/detail/mixmax-email-tracking-tem/ocpljaamllnldhepankaeljmeeeghnid?hl=en) installed. Its primary purpose is to show contextual information about a particular email address (though this will change in the future as more APIs are added). In the top of the sidebar it shows the selected contact, and then beneath it lists tabs of "sidebar integrations" that you have installed. A sidebar integration is a standalone website that is loaded inside an iframe that can respond to a new contact being "selected" via a Javascript API. Through the Mixmax Sidebar SDK discussed here, you can add your own sidebar to Mixmax. This makes it possible to extend Mixmax with your own tools. Mixmax comes with two built-in sidebar integrations: * Contact profiles - lists contact profiles for the selected contact * Salesforce ([Growth](https://mixmax.com/pricing) or above only) - syncs the contact to Salesforce [block:image] { "images": [ { "image": [ "https://files.readme.io/73af028-Screen_Shot_2017-03-28_at_3.52.45_PM.png", "Screen Shot 2017-03-28 at 3.52.45 PM.png", 271, 469, "#3c577e" ], "caption": "The Mixmax sidebar in Gmail" } ] } [/block] [block:api-header] { "title": "Adding your sidebar integration to Mixmax" } [/block] You can add a sidebar integration to Mixmax in your [developer settings dashboard](https://app.mixmax.com/dashboard/settings/developer). You will need [Growth](https://mixmax.com/pricing) or above for access—email support@mixmax.com for a free trial. This will add the sidebar integration for your personal use. You may also share it with individual users, by email, or with your Mixmax team(s). When you're ready to release your integration to all Mixmax users, email us at support@mixmax.com with your request. ## Parameters To add your sidebar integration, you will need a few pieces of information: ### Name The name of your integration to show up in developer settings. ### URL The URL of your integration. The webpage at this URL should use the Sidebar SDK, as described in the following sections, to communicate with the Mixmax extension. ### Tab icon There are two ways to specify the icon used to represent your integration's tab in the Mixmax extension: * you can provide the URL of an image, or * you can provide the name of a [Font Awesome](http://fontawesome.io/icons/) icon such as "info-circle" _and_ a color, specified as a hex value, such as "#8a8a9e". You must specify either an image _or_ both the name _and_ color. [block:api-header] { "title": "Loading the Sidebar SDK" } [/block] Include the following line of Javascript in your website: [block:code] { "codes": [ { "code": "<script defer src=\"https://sdk.mixmax.com/v1.5.2/sidebar.umd.min.js\"></script>", "language": "html" } ] } [/block] The script will create the global object `Mixmax.sidebar`. See below for its use. If you're using a JavaScript bundler like [Rollup](https://rollupjs.org/) or [Webpack](https://webpack.github.io/), instead of loading the SDK using a script tag, you can import the SDK from npm like [block:code] { "codes": [ { "code": "const Mixmax = require('@mixmaxhq/sdk');\n\nMixmax.sidebar.on('contactSelected', (contact) => console.log(contact));", "language": "javascript" } ] } [/block] If your bundler is capable of importing ES6 modules and understands `pkg.module`, you can import the SDK like [block:code] { "codes": [ { "code": "import { sidebar } from '@mixmaxhq/sdk';\nsidebar.on('contactSelected', (contact) => console.log(contact));\n\n// If your bundler understands [`pkg.browser`](https://github.com/defunctzombie/package-browser-field-spec)\n// like Rollup does when using rollup-plugin-node-resolve with\n// [`browser: true`](https://github.com/rollup/rollup-plugin-node-resolve#usage),\n// you can import the Sidebar SDK directly. This is not only a more concise\n// import but may actually lead to bundling less JS due to \n// https://github.com/rollup/rollup/wiki/Troubleshooting#tree-shaking-doesnt-seem-to-be-working\nimport sidebar from '@mixmaxhq/sdk/sidebar';\nsidebar.on('contactSelected', (contact) => console.log(contact));", "language": "javascript" } ] } [/block] [block:api-header] { "title": "Using the Sidebar SDK" } [/block] Once you have loaded the `sidebar` object, you can use it to listen for events from the Mixmax extension telling you when and how to update your sidebar integration. The `sidebar` object is an [`eventemitter3`](https://www.npmjs.com/package/eventemitter3#usage) instance, so you register event listeners like [block:code] { "codes": [ { "code": "sidebar.on('contactSelected', (contact) => console.log(contact));", "language": "javascript" } ] } [/block] ## Events The events that the object emits are: ### Event: 'contactSelected' Arguments: * _contact_ `<Object>` A contact that the user just selected, for instance by hovering over an email address in Gmail. This object will have the following properties: * `email` `<String>` The email address of the contact. * `fullName` `<String>` (Optional) The full name of the contact, if available. * `image` `<String>` (Optional) The URL of an image for the contact. When you receive this event, you should populate your integration with information related to the contact. For instance, if your integration represented a task manager, your integration might display a list of tasks assigned to this contact. ### Event: 'beforeContactSelected' Arguments: * _event_ `<Event>` Listening to this event is optional. You should listen to this event if you wish to prevent the sidebar from selecting a new contact, perhaps because the user has not finished editing information in your integration related to the current contact. Calling `event.preventDefault()` will prevent the sidebar from updating to show the new contact. (The user will then have to re-select that contact at some later point, at which time this event will be emitted again.) ### Event: 'clear' No arguments. When you receive this event, you should clear your integration of the information it is currently displaying. This event is not currently emitted but may be in the future.