Poll unit integration

The poll unit code snippet consists of a <script> and a <div> tag that will display the poll unit.

The poll unit integration will typically be handled by the media partner's content management team with the assistance of the CivicScience Account Management team. In some cases, an initial review by the media partner's development team is necessary for approval and proper integration. The CivicScience development team is available to discuss the code and proposed integration before setup and to review any deployments.

There are several ways you can integrate poll units into your site. The first, covered here, assumes that you have access to the code of the site. The second uses Google Tag Manager. The third, fourth, and fifth methods are for sites that use WordPress as their content management system (CMS). In any case, the first few steps will always be the same.

Initial Setup

There is an initial setup that synchronizes CivicScience & media partner IDs. For most media partners, the initial setup will be handled by the CivicScience development team.

The CivicScience development team will build a script to synchronize the media partner and CivicScience unique user IDs (UUID). Discussions with the media partner development team might be necessary to complete this step, especially if the media partner desires bidirectional synchronization.

Placement and Styling

The poll unit will appear on the web page wherever the code snippet is placed. The best placement for it is embedded directly into an article's content. In general, instances of a poll unit placed closer to the top of the page gather more responses.

A poll unit will expand to fit the space of the container in which it is placed. The media partner can add margins and padding to the container or to outer elements wrapping the container (elements under the media partner's control) to adjust the spacing between the poll unit and other parts of their page. A poll unit will automatically fill the width of its container. Thus, the media partner can apply their own stylesheet rules to the container or elements wrapping the container to ensure that the poll unit has the appropriate width. As questions of varying lengths appear in the poll unit, the default size of the instance will grow and shrink vertically, sometimes shifting the content below it.

It is important not to wrap a poll unit in an element with a fixed height. Doing so is likely to either waste space if the container is too tall or hide the answer choices if it is too short. Either scenario will impact engagement rates and the ability to collect responses.

Please note that a poll unit will not achieve full functionality if it is deployed inside an <iframe>. If the site architecture requires deployment within an <iframe>, additional steps may be necessary for the poll unit's integration. It’s best to have the integration process reviewed by both CivicScience and the media partner's developer team if an <iframe> installation is required.

Basic Integration

The basic poll unit integration code can be found in the InsightStore on your target's Target > Settings > Integration page, or the media partner's CivicScience account manager can supply the code. The integration code is an HTML snippet. An example follows. 

<div id="civsci-id-123456789" data-civicscience-Widget="000"></div>
<script type="text/javascript" async src="https://get.civicscience.com/jspoll/5/csw-polyfills.js"></script>

The "000" value for the data-civicscience-Widget attribute in the example will be replaced with the media partner's target identifier, either a number or a Unique User Identifier (UUID).

Once downloaded from the InsightStore, the media partner places the snippet in the HTML code for their page wherever they'd like the poll unit to appear.

Poll Unit Demonstrations

 Examples of poll units in action may be viewed here.