Contents x
    Poll Unit Technical Documentation
    • 19 Sep 2023
    • 9 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    Contents

    Poll Unit Technical Documentation

    • Updated on 19 Sep 2023
    • 9 Minutes to read
    • Contributors
    • Print
    • Dark
      Light
    Article Summary

    Integration

    Basic

    The basic poll unit integration code can be found in the InsightStoreTM on the Target > Settings > Integration page for the target associated with your website. You must be a Civic Science Media Partner to access the poll unit integration code. The integration code is an HTML snippet which looks something like this:

    <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 must be replaced with your poll unit target identifier, either a number or a UUID.

    Here is a more complex example snippet with data-civicscience-article-url:

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

    The data-civicscience-article-url is optional. 

    NOTE: data-civicscience-article-url should only be used when the poll unit integration code is being loaded from inside an <iframe>. If the poll unit is loaded inside an <iframe>, data-civicscience-article-url is required to identify the exact URL of the web page that is parent to the containing <iframe>. If the poll unit is placed inside an <iframe> without a unique data-civicscience-article-url set, certain features like sharing, pinning questions, and using recommended questions will not work.

    Place the integration code snippet in the HTML code for your page wherever you'd like the poll unit to appear.

    Advanced

    The basic integration code is suitable for most websites. This section describes a more advanced integration method.

    Container Element and Placement

    The best placement for the poll unit is embedded in an article's content. Other popular placements include below an article, on section pages, or on the page's right (or left) side column. Instances of the poll unit placed closer to the top of the page tend to gather more responses.

    Many HTML elements are okay to use for the poll unit container, but generally, it makes the most sense to use a <div> element.

    The element must have an id attribute with a value that is distinct from any other id attributes on the page. The data-civicscience-widget attribute is the target identifier, as explained above.

    Here is an example of a poll unit container element:

    <div id="civsci-id-123456789" data-civicscience-widget="000"></div>

    The container must be empty of content. Any content inside the container will be replaced when the poll unit is loaded.

    JavaScript Library

    Include the poll unit JavaScript library on the page by including this element;

    <script type="text/javascript" async src="https://get.civicscience.com/jspoll/5/csw-polyfills.js"></script>

    HTML

    You can place the script element in the <head> section of your HTML code or at the end just before the </body> closing tag.

    You only need to include the script once on the page, even if your page includes more than one instance of the poll unit.

    We also ship a lighter version of the library without polyfills but be warned that the poll unit may not work in older browsers such as Internet Explorer 11 without them.

    <script type="text/javascript" async src="https://get.civicscience.com/jspoll/5/csw.js"></script>

    Poll Unit Function

    The poll unit JavaScript function is called to load the instance into the container. The function accepts one argument: an object providing the poll unit settings.

    Here is a basic example:

    civicscience.widget({
target: "000",
container: "#civsci-id-1233904299"
});

    The target setting is your poll unit target identifier, usually a number or a UUID.

    The container setting is a CSS selector uniquely identifying the poll unit container element.

    Here is a more complex example with articleUrl, recommended for the poll unit integration code placed inside an <iframe>:

    civicscience.widget({
target: "000",
container: "#civsci-id-1233904299",
articleUrl: "https://url-to-article",
forceDarkMode: false
});

    The articleUrl is optional. NOTE articleUrl should only be used when the poll unit integration code is being loaded from inside an <iframe>. If the poll unit is loaded inside a wrapping <iframe>, articleUrl should identify the exact URL of the web page that is parent to the containing <iframe>. If the poll unit is placed inside an <iframe> without a unique articleUrl set, certain features like sharing, pinning questions, using recommended questions, and the poll unit positioning will not work.

    The forceDarkMode is optional. NOTE forceDarkMode should only be used when the web page containing the poll unit forces a dark mode on the user, regardless of the user's Operating System Dark Mode settings. It is recommended that Dark Mode be enabled for the Poll Unit in the InsightStoreTM Target > Settings > Theme page instead of using the forceDarkMode poll unit function parameter.

    Both the target and container settings are required.

    Multiple Instances of the Poll Unit

    You can include more than one instance of the poll unit on a page by placing multiple copies of the integration code in the HTML code for your page. Make sure that you use different id attributes for the <div> element in each placement of the integration code.

    When more than one instance of the poll unit is included on a page, each instance is unaware of the others and, particularly, of which questions are being asked in the other instances during that page visit. Thus, it is possible for a respondent interacting with multiple instances on the page during a single page visit to be asked the same question more than once.

    Customization

    This section discusses some parts of the poll unit that CivicScience can customize for your website.

    Position and Dimensions

    The poll unit will appear on your web page wherever the integration code, particularly the container <div> element, is placed. With custom CSS, margins and padding can be added to the container or to outer elements wrapping the container (elements under your control) to adjust the spacing between the poll unit and other parts of your page.

    The poll unit will automatically fill 100% of the width of its container. Thus, you can apply your own stylesheet rules to the container or elements wrapping the poll unit container to ensure that it has the appropriate width.

    As questions of different lengths are asked in the poll unit, it will grow and shrink vertically, sometimes shifting the content below it. It is important not to wrap the poll unit in an element with a fixed height, such as an <iframe>. Doing so is likely to either waste space due to the container being too tall or hide part of the poll unit due to it being too short.

    Font

    The poll unit can be configured with font size and font family to closely match the look of your website. This can be done in the Target > Settings > Theme page in the InsightStoreTM.

    The poll unit looks best when it is displayed in a sans-serif font. Even if your website uses predominantly serif fonts, CivicScience recommends using a sans-serif font for the poll unit. The browser's default sans-serif font usually works well.

    The layout of the controls and sections of the poll unit is relative to the font size. Therefore, the layout will naturally become chunkier or more compact to match the size of the text.

    Colors

    The poll unit can be configured to use a custom color for the results bar charts that appear at the end of a Respondent's visit. A light tint of a color associated with your brand or website is usually a good choice. This can be set in the Target > Settings > Theme page in the InsightStoreTM.

    CivicScience also provides the option to use tints of the same custom color for the answer choice buttons as an alternative to the default blue color.

    In some cases, CivicScience will use colors other than the custom color for results. An example is quiz question results, which feature green colors for correct and red colors for incorrect answers.

    Title

    The poll unit title is a good opportunity to make the poll unit look like a part of your website. CivicScience can customize the title text and many other CSS properties of the title, including borders, padding, and font characteristics. This can be done in the Title field on the Target > Settings > Theme tab in the InsightStoreTM.

    Privacy Policy

    The poll unit will always show the CivicScience privacy policy in the drawer menu. In the InsightStoreTM at Target > Settings > Customization, it is possible to configure the poll unit to also show a partner-specific privacy policy link.

    Responsive Layout

    Because the poll unit automatically fills 100% of its container's width and its layout is designed to scale well, given an appropriate font size, in most cases, the poll unit will fit nicely on a responsive website without any special customization.

    For more complicated responsive websites, we have the capability to incorporate @media query breakpoints in some aspects of the customization.

    Fixed Layout

    Configuring the poll unit as a fixed-size container is possible, but there is some user experience degradation, so we do not recommend it. The vertical overflow will scroll in the fixed-size container. If you need the poll unit to be placed in a fixed-size container, contact your CivicScience account manager.

    Dark Mode Support

    The poll unit supports dark mode. There are two ways to enable dark mode.

    • (Recommended) Dark mode for the poll unit styling can be configured to follow the user's operating system dark mode preference. Enabling this can be done with the Dark Mode Allowed checkbox on the Target > Settings > Theme page in the InsightStoreTM.
    • (Not recommended, but supported) Adding the following data attribute to the poll unit integration code will enable dark mode programmatically, ignoring the user's operating system preference. The integration code would look like the following:
    <div id="civsci-id-123456789" data-civicscience-widget="000"
data-civicscience-force-dark-mode="true"></div>
<script type="text/javascript" async src="https://get.civicscience.com/jspoll/5/csw-polyfills.js"></script>

    The same will be accomplished by using the poll unit function integration property forceDarkMode (Boolean):

    civicscience.widget({
target: "000",
container: "#civsci-id-1233904299",
forceDarkMode: true
});

    A note regarding dark mode: If your instance of the poll unit has custom CSS styling, the CSS may need to be updated to handle dark mode. Here is an example of what that CSS might look like.

    /*Example custom css styling that works only in dark mode*/
html.csw-html .csw.csw-dark-mode a {
color: dodgerblue;
}

    Forward Compatibility Warning

    We are always improving the poll unit and developing new features and capabilities. To make those features available in the poll unit quickly, we may change the HTML structure of the poll unit at any time and without notice.

    The customization settings described in this article are designed to be compatible with future changes we make to the poll unit. By limiting the degrees of customization, we preserve our ability to develop great new features and protect you from unexpected compatibility issues.

    Be careful not to write any CSS or JavaScript code of your own that targets or relies upon the internal HTML structure of the poll unit, including DOM classes. We cannot guarantee that future iterations of the poll unit will be compatible with that code.

    More Technical Details

    Performance

    Asynchronous JavaScript

    The async attribute on the poll unit integration code <script> element instructs the browser to load the poll unit JavaScript library asynchronously without pausing the page from rendering while the script is downloaded. JSONP requests during the poll unit life-cycle are also asynchronous.

    Caching

    To facilitate rapid deployment of bug fixes and new features without requiring our partners to adjust the poll unit integration code, requests for the poll unit JavaScript require a trip to our server. However, our server is configured to respond with 304 Not Modified when possible, saving the bandwidth that would otherwise have been required to download the entire library.

    A/B Testing

    To improve the poll unit, we will occasionally conduct A/B tests for various characteristics. Whether an individual is in the A or B groups for the test depends on his or her respondent cookie identifier. Thus, the same user with the same computer and browser will generally have a consistent experience. However, the experience may differ for two respondents or even the same respondent using a different computer or browser.

    Was this article helpful?
    What's Next
    Follow Us
    © 2023 CivicScience, Inc. All Rights Reserved