Questions & Variables

When an end-user opens the Insight, a question dialog corresponding with the variables you've defined is presented as below:

End-user questions based on the defined variables

Adding variables

The first step when creating a Insight is to decide if it needs any variables (inputs). Variables are presented to end-users of the Insight or template in the form of a question, and the options presented depend on what type of variable is used.

To define a new variable, click the Custom menu at the top and select Variables / Questions:

Define a new variable

Variables can be divided into three categories:

Simple variables — a simple number, boolean, date or text (can be displayed as an options dropdown). An example is the monthly advertising budget in dollars.
Event variables — a specific event. Can be used for example to give insight into what behavior leads to payment, which is the conversion event input variable.
User/event property variables — a specific number, boolean, date or text property of a specific event or user. An example of an event property variable could be the price of the item for the add to cart event, used for example to give insight into shopping cart abandonment related to value added to cart. Similarly, user properties can be defined as input variables and be used in any analysis.

Click the dropdown Select variable type and then choose Template Variables. For simple variables as describe above, choose one of Text, Number, Date or Yes/No. For event variables select Event. For User/Event property variables choose either the correct type from Event Property or User Property.

The question to the end-user can be specified in the field Question for end-user.

The description is optional, and can be used to give the end-user some ideas on what values to pick.

Under Enter a variable name enter a valid JS variable name (use only letters, numbers and underscores), and a default value like 7, e.g. for a pre-filled number of days to forecast.

By checking This variable is optional, the end-user doesn't have to answer the question.

For event and user properties, if a specific property like price of the event add to cart is not available, but only the event add to cart, the end-user can for the value of price use an average item price such as 99 instead. If you don't want to allow the end-user to specify such values as substitutes for actual values, check [✅] Don't allow manual user substitute values.

The final option is to decide if this variable should show up as soon as the end-user opens the Template, or only when a specific Insight is opened. For the later check [✅] This variable is needed only for Insights and then visit the Custom Insight from the top Custom menu to edit your Insight. Then under the section Select variables for Insight choose any Insight only variables. Template variables can be shared and used in all Insights, reports, intelligence, segments and user properties within a Template, while an Insight only variable are only available to that specific Insight.

note

If you'd like to pass through the end-user's answer as input parameter of an Intelligence plugin's input data parameter, choose here the Template Variables and then Event Property, with the right type of the parameter. For more details see the working with Intelligence plugins section later.

The reason is that Intelligence plugin input data is always based on specific properties of events a user interacted with. For example, a recommender plugin may use the color property of the view_item event, as input data to build a recommender model based on the color of items users have interacted with.

Reading assigned variables

Once the end-user has assigned all questions, they are available in the JS and JSX contexts using the global variable questions. For the example questions dialog screenshot above, here is how the questions JSON object looks like:

{
  "conversion_event": {
    "name": "payment_completed",
    "value": null,
    "valid": true,
    "event": "payment_completed"
  },
  
  "monthly_budget": {
    "name": "3000",
    "value": 3000,
    "valid": true
  },
  
  "add_to_cart_value": {
    "name": "price",
    "value": "e_col_e9f40e1f1d1658681dad2dac4ae0971e",
    "valid": true,
    "event": "payment_completed",
    "substitute": false
  },
  
  "campaign_source": {
    "name": "initial_campaign_source",
    "value": "u_col_initial_campaign_source",
    "valid": true
  }
}

Each key corresponds with the variable name specified. Each object has a few keys:

name — a human readable name that can be presented to end-users. For events this is the event name, for user/event properties this is the human readable name of the property.
value — the value chosen by the end-user. For simple variables this is the value as-is. For user/event properties this is the actual property field such as u_col_initial_campaign_source which can be used in reports, intelligence, custom SQL and more.
event — only available for event variables. This is actual name of the event such as payment_completed, and can be used in reports, intelligence, custom SQL and more.
valid — if a variable is optional this property is true if the end-user has filled in the value, and false if left empty.
substitute — if a user/event property variable allows end-user substitution, this is set to true. Used when the end-user used a substitute value for an event/user property, such as 99 instead of an actual event numeric property.

#Adding variables

note

#Reading assigned variables

Adding variables

Reading assigned variables