Using the Javascript API to specify user IDs and custom properties

Using Informizely's Javascript API you, or your developer, can associate any number of custom properties ("name-value" pairs) with a response. Each custom property that is set on a page where a survey is shown is displayed in the details section for the response on the reporting pages. These custom properties can also be used to target your surveys against.

Example

You want to show a survey only to visitors that made a purchase in the last 7 days. Informizely can't know whether this is the case, but your website knows this. In this case your website could, using the Javascript API, set the custom property made-purchase to the value yes. In the survey's targeting settings you would then add the custom property "made-purchase=yes". Note that you can set any number of custom properties and that the texts used in the name-value pair are completely up to you. Informizely does not interpret these texts in any way, other than to match them with the currently set custom properties.

User identification

If your website has registered users, and you want to target your survey to some or all registered users, or to unidentified users, you could use custom properties, like in the example above. But especially for this case Informizely's Javascript API has a special setting. Your website can set the current user's ID to any identifying property, e.g. the user's email address or customer ID. You can then target your survey to some or all identified users, or to unidentified users, using the survey's target setting "Target (un)identified users". The user ID will be shown in the response view for all responses where it was set.

Using the Javascript API

It's very simple to pass data to the Informizely widget using the Javascript API: first you retrieve a handle to the "api" object, and then you call the appropriate functions on it.

Note: the term "insitez" used below refers to the previous name of Informizely.

To retrieve the "api" object, add the following code directly before the normal Informizely code snippet: <script type="text/javascript"> var IzWidget = IzWidget || {}; IzWidget['insitez.ready'] = function (api) { // Store or use the 'api' object here. }; </script>

To set the user ID, call api.set('userId', '<<<USER-ID>>>'), where <<<USER-ID>>> is replaced with the current user's identifying property, e.g. his email address.
To set one or more custom properties, call api.set('custom', { <<<name-value-pairs>>> }), where <<<name-value-pairs>>> is replaced by one or more 'name':'value' pairs, separated by commas.

These API functions can be called any number of times. At every call the Informizely widget will check if there are surveys to be displayed.

Complete example

<script type="text/javascript"> var IzWidget = IzWidget || {}; IzWidget['insitez.ready'] = function (api) { api.set('custom', { 'made-purchase': 'yes', 'shopping-cart-empty': 'no' }); api.set('userId', "user1@mysite.com"); }; </script>

You can target a survey on custom properties on the survey's "TARGET > ADVANCED" tab.
When using custom properties for targeting, mostly one name=value pair is used, e.g. showSurvey=true. You can specify multiple name=value pairs by placing them on separate lines: By default newlines are interpreted as AND, so the survey is only eligible to be shown when all custom properties match their specified value. You can specify multiple name=value pairs on one line, separated by a comma, indicating that at least one of the values must match, i.e. the commas are interpreted as OR. The following specifies that property "language" must have the value "en" AND that property "country" must have either the value "UK" OR "US". You can change the interpretation of newlines to OR and that of commas to AND by specifying OR-AND on the first line. The following specifies that the survey is eligible to be shown when the custom property "country" has the value "UK" OR when "country" has the value "US" AND property "language" has the value "en":

• To specify that a property must be present (set) but the value is irrelevant, leave the value empty: property=.
• To specify that a property must not be present, set the value to "missing": property=missing.
• To specify that a property must not have the value "X", use the NOT() function: property=NOT(X).
• To match the value of a property to a regular expression, use the REGEX() function. Some examples:
  
  property=REGEX(term) matches all values that include the text "term". E.g. "terminal".
  property=REGEX(^term) matches all values that start with the text "term". E.g. "terminal", but not "short-term".
  property=REGEX(term$) matches all values that end with the text "term". E.g. "short-term", but not "terminal".
  property=REGEX(term.+) matches all values that include the text "term", followed by at least one other character. E.g. "term12", but not "term".