Embed Code

The Polis embed code allows conversation owners to add the conversation to any third party website they control in the form of an iframe generated by an html script tag. This does mean you have to allow third party JavaScript to run on your property. This is unlike YouTube, for instance, which only requires an iframe: embedded YouTube videos are not responsive to browser width. Polis is, and uses JavaScript to solve this problem reliably.

The code that generates the iframe is open source and can be found here: https://pol.is/embed.js and https://github.com/compdemocracy/polis/blob/dev/client-participation/api/embed.js

Events

The Polis embed code and iframe are configured to emit a "vote" event each time a participant votes. You can subscribe to those events on the page that instantiates the iframe like this (assuming you're using the hosted instance at pol.is):

window.addEventListener("message", function(event) {
  var data = event.data || {};
  if (!event.origin.match(/pol.is\$/)) { return; }
  if (data.name === "vote") { alert("vote!");
}

Per User Config

Each time Polis loads into an embedded context, you can optionally configure Polis at the user level to hide or show facets of the interface. You can do this by adding different flags to the <div> shown below. You might set data-ucw (user can write) false, for instance, if the user isn't logged into your system. This allows flexible usage and deployment of the system.

Using data- attributes to customize behavior is an established pattern in web engineering. If you're a web engineer interested in examining best practices, see Google's implementation of programmable search: https://developers.google.com/custom-search/docs/element which uses the same combination of <div class=" and a script tag which targets the element's class attribute, using data- attributes to override default behavior.

<div
  class="polis"
  data-page_id="your_pageid_1234"
  data-site_id="polis_site_id_your_site_id_goes_here"
  data-ucv="true"
  data-ucw="false"
  data-show_vis="true"
></div>
<script async="true" src="https://preprod.pol.is/embed.js"></script>

Hiding the comment submit form

The data-ucw (user can write) tag toggles writing, and is only relevant for that user for that session.

Hiding voting interface

The data-ucv (user can vote) tag toggles voting, and is only relevant for that user for that session.

Hiding the visualization

The data-show_vis is a toggle that causes the vis to be enabled or disabled when the conversation initializes. This is a one-time setting which is picked up and stored in our db the first time someone loads this script. This is a convenience method if you are creating conversations implicitly from embed codes, rather than from the admin dash.

If you later change this value in the embed code, it won't have any effect. To change that value, you can load the configuration tab of the admin page for that conversation (and of course ensure an embed code isn't resetting it).

Full list:

• xid: linkage to external identity
• ucv: user can vote
• ucw: user can write comments
• ucsh: user can see header
• ucsd: user can see description
• ucsf: user can see footer
• show_vis: user can see visualization
• build
• x_name
• x_profile_image_url
• ui_lang: set the language of the participation interface for all participants. This relies on the existence of community contributed translations for the given language
• ucsv
• ucst
• subscribe_type
• show_share
• bg_white
• auth_needed_to_vote
• auth_needed_to_write
• auth_opt_fb
• auth_opt_tw
• auth_opt_allow_3rdparty
• dwok
• topic