03/25/2020
The basic widget integration code can be found in the InsightStore on the Target Settings Integration page for your widget target. You need to be a Civic Science Publisher Partner to be access to the widget code. The integration code is an HTML snippet, and it usually looks something like this.
<div id="civsci-id-1233904299" 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 should be replaced with your widget target identifier, either a number or a UUID.
Simply place the integration code snippet in the HTML code for your page wherever you'd like the widget to appear.
The best placement for the widget is embedded in article content. Other popular placements include below an article, section pages, or the right (or left) side column of the page. In general, widgets placed closer to the top of the page tend to gather more responses.
You can include more than one widget 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 widget is included on a page, each widget is unaware of the others and in particular of which questions are being asked in the other widgets during that page visit. Thus it is possible for a respondent interacting with multiple widgets on the page during a single page visit to be asked the same question more than once.
The basic integration code is suitable for most websites. This section describes a more advanced integration method.
Include the widget 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>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 widget.
We also ship a lighter version of the library without polyfills, but be warned the widget may not work in older browsers such as IE11.
<script type="text/javascript" async src="https://get.civicscience.com/jspoll/5/csw.js"></script>Many HTML elements are okay to use for the widget 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.
Here is an example of a widget container element.
<div id="civsci-id-1233904299"></div>The container should be empty of content. Any content inside the container will be replaced when the widget is loaded.
The widget JavaScript function is called to load the widget into the container. The function accepts one argument which is an object providing the widget settings.
Here is an example.
civicscience.widget({
target: "000",
container: "#civsci-id-1233904299",
});The target setting is your widget target identifier, usually a number or a UUID.
The container setting is a CSS selector which uniquely identifies the widget container element.
Both the target and container settings are required.
Detailed user research has been conducted to create a widget experience that will delight respondents and encourage them to answer questions. Thus there are some aspects of the widget which cannot be adjusted. This section discusses some parts of the widget which we can customize for your website.
The widget will appear on your web page wherever the integration code, and in particular the container <div> element, is placed. You can add margins and padding to the container or to outer elements wrapping the container, elements under your control, to adjust the spacing between the widget and other parts of your page.
The widget will automatically fill the width of its container. Thus you can apply your own stylesheet rules to the container or elements wrapping the container to ensure that the widget has the appropriate width.
As questions of different length are asked in the widget, the default widget will grow and shrink vertically, sometimes shifting the content below it. It is important not to wrap the widget in an element with a fixed height, such as an <iframe>. Doing so is likely to either waste space for the container being too tall or hide the bottom part of the widget for being too short.
We can configure the font size and font family to match the look of your website.
The widget looks best when it is displayed with a sans serif font. If your website uses a sans serif font, that is a good choice for the widget too. If your website predominantly uses serif fonts, we still recommend using sans serif for the widget, and usually the browser default sans serif font works well.
The layout of the controls and sections of the widget is relative to the font size. Therefore the layout will naturally become chunkier or more compact to match the size of the text.
We can pick a custom color for the results bar charts that appear at the end of a widget visit. Usually a light tint of a color associated with your brand or website is a good choice.
We also provide 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, we will use colors other than the custom color for results. An example is for quiz question results, which feature green and red colors for correct and incorrect answers.
The widget title is a good opportunity to make the widget look like a part of your website instead of like an ad. We can customize the title text and many other CSS properties of the title, including borders, padding, and font characteristics. This is a place where a serif font is appropriate if that is the style you use on your website.
We can customize the subtitle to associate your brand and CivicScience together as presenters of the widget content. We have observed that this co-branding builds trust with respondents and encourages them to participate in the poll.
The widget will always show the CivicScience privacy policy in the drawer menu. It is possible to configure the widget to additionally show a publisher specific privacy policy.
Because the widget automatically fills the width of its container and because the widget layout is designed to scale well given an appropriate font size, in most cases the widget will fit well in 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.
It is possible to configure the widget as a fixed size container, and the vertical overflow will scroll in that container. If you need a widget to be placed in a fixed size container, contact your CivicScience account manager. That is possible but there is some degradation in user experience, and therefore it is not recommended.
We are always tinkering with the widget and developing new features and capabilities. To make those features available in the widget quickly, we may change the HTML structure of the widget at any time and without notice.
The customization settings described in this section are designed to be compatible with future changes we make to the widget. By limiting the degrees of customization, we reserve 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 which targets or relies upon the internal HTML structure of the widget, including DOM classes. We cannot guarantee that future iterations of the widget will be compatible with that kind of code.
We use several different methods for identifying and remembering respondents and to combine each respondent's answers from multiple widget visits into one profile.
Our most common identification mechanism is a cookie which is placed by the widget. After getting affirmative consent from a respondent that person is assigned a long random sequence of characters as his or her unique identifier and stored in a cookie. The cookie is associated with the civicscience.com domain. This cookie is considered first party when accessing resources on civicscience.com and third-party when accessing your domain.
An increasing number of modern browsers disable third-party cookies by default or prohibit them entirely, and privacy-conscious users can install software that disables tracking with third-party cookies. For this reason we provide some other identification mechanisms too.
We use HTML5 local storage to store a backup identifier for the respondent in case the cookie identifier is not available. The local storage identifier is different for each website even for the same person. In other words the same person will be treated as a different respondent on two different websites. However for visitors who visit your website frequently, the local storage identifier is an effective fallback option which bypasses cookie restrictions.
The async attribute on the widget integration code <script> element instructs the browser to load the widget JavaScript library asynchronously without pausing the page from rendering while the script is downloaded. JSONP requests during the widget life-cycle are also asynchronous.
To facilitate rapid deployment of bug fixes and new features without requiring our partners to adjust the widget integration code, requests for the widget 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.
To improve the widget we will occasionally conduct A/B tests for various characteristics. Whether an individual is in the A group or the B group for the test is based 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.