The Picked SDK sends an analytics event for each action of a visitor. This page names every
event type, every interaction type, and every schema that the SDK sends.
Two terms carry the page:
An event type is the name of the event. It is the event_type column in PickedQL.
A context is a block of data that the SDK attaches to an event. Picked makes a
column from each one. An example is the product_list context behind dim_product.
Every table below marks a context as always attached or as attached when available.
The SDK attaches a context in the second group only when it has the data at that moment.
An event outside an experience has no experience context.
Contexts on every event
The tracker attaches two contexts to every event: app, with the project ID, and
deployment, with the environment of the SDK. It also attaches cvly_x, but only for a
site on Vercel.
The tables below never list deployment or cvly_x. They list app only where the
tracker of that event attaches it a second time.
Event types
Experience events
The analytics plugin sends these events. They come from the client SDK, and they need no
code of yours.
Event type
When it fires
Always attached
Attached when available
app_load
The SDK loads on the page.
feature_list, session
experience, step
app_initialize
The SDK completes its start-up and is ready.
feature_list, session
experience, step
experience_load
An experience starts.
experience, feature_list, session
step
app_open
An experience opens.
feature_list, session
experience, step
app_close
An experience closes.
feature_list, session
experience, step
feature_decide
A feature flag gets its bucket for this visitor.
feature_list, session
experience, step
An experience in an <ExperienceSlot> sends experience_load when the slot mounts it in
the browser. The slot shows the experience when it is open and when it is closed:
With open="rule", an experience that has no initializeOpen value does not open. It sends
no app_open.
When the slot stops rendering an experience, the experience sends no app_close.
The analytics plugin sends step_enter, step_submit, step_submit_success,
form_submit, form_submit_success, form_submit_error, and field_validation_error. The
SDK has a tracker for step_submit_error and step_complete, but it starts neither of
them. Call the tracker from your own code.
Event type
When it fires
Always attached
Attached when available
step_enter
The visitor arrives at a step of a flow.
feature_list, session, step
experience, field_list
step_submit
The visitor submits a step.
feature_list, session, step
experience, field_list, response_list
step_submit_success
The step submission is accepted.
feature_list, session, step
experience, field_list, response_list
step_submit_error
A step submission fails. Your code sends it.
exception, feature_list, session, step
experience, field_list, response_list
step_complete
A step reaches its end state. Your code sends it.
feature_list, session, step
experience, field_list, response_list
form_submit
The visitor submits a form.
feature_list, form, session
experience, step
form_submit_success
The form submission is accepted.
feature_list, form, session
experience, step
form_submit_error
The form submission fails. The reason is in exception.
exception, feature_list, form, session
experience, step
field_validation_error
A field value fails a validation rule.
exception, feature_list, session
experience, form, step
Ecommerce events
Three sources send these events: the template for Google Tag Manager, the Picked app for
Shopify, and your own code. The template for Google Tag Manager sends every event of this
group. "Shopify behaviour" below covers the Picked app for Shopify.
Event type
When it fires
Always attached
Attached when available
cart_add
A product goes into the cart.
app, feature_list, product_list, session
experience, step
cart_remove
A product leaves the cart.
app, feature_list, product_list, session
experience, step
checkout_start
The visitor starts a checkout.
app, feature_list, product_list, session
experience, step
checkout_complete
The visitor completes a checkout. It is the default conversion of PickedQL.
app, feature_list, order, product_list, session
experience, step
order_create
An order becomes a record in the store.
app, feature_list, order, product_list, session
experience, step
product_list_view
The visitor sees a list of products, such as a collection.
app, feature_list, product_list, session
experience, step
product_select
The visitor chooses a product from a list.
feature_list, product_list, session
experience, step
product_view_details
The visitor opens the detail page of a product.
app, feature_list, product_list, session
experience, step
search_results_list_view
The visitor sees a list of search results.
feature_list, product_list, session
experience, step
recommendation_present
A step shows a recommendation to the visitor.
feature_list, product_list, session
experience, step
wishlist_add
A product goes onto a wishlist.
feature_list, product_list, session
experience, step
waitlist_join
The visitor joins a waitlist.
app, feature_list, session
experience, product_list, step
is_purchase is 1 for checkout_complete and 0 for every other event. is_cart_add is 1
for cart_add. Both columns are on events and on metrics.
Shopify behaviour
The Picked app for Shopify sends a part of this group from a web pixel, and one event from
the server.
Picked event
Shopify source
cart_add
The product_added_to_cart pixel event. The product_list context holds the one cart line, and not the whole cart.
cart_remove
The product_removed_from_cart pixel event, with the same one cart line.
checkout_start
The checkout_started pixel event. The session context also gets shopify_checkout_token.
checkout_complete
The checkout_completed pixel event. The order context is there only when the checkout has an order.
order_create
The orders/create webhook, from the server and not the browser. The event time is the creation time of the order.
product_list_view
The collection_viewed pixel event.
product_view_details
The product_viewed pixel event, for one product variant.
page_view
The page_viewed pixel event.
identify
The picked:session pixel event.
For a Shopify store, the session context also holds shopify_client_id,
shopify_customer_id, and shopify_checkout_token. The order context holds the Shopify
checkout_token and cart_token. The Shopify pixel sends no other event type of this page.
Page and session events
Event type
When it fires
Always attached
Attached when available
page_view
The visitor opens a page.
app, feature_list, session
experience, product_list, step
identify
The SDK connects the session to a known person or store client.
app, session
experience, feature_list, step
lead_capture
The visitor gives contact details.
feature_list, session
experience, step
lead_created
The Picked API records the lead from a capture.
app, session
None.
modal_open
A modal opens.
feature_list, modal, session
experience, step
modal_close
A modal closes.
feature_list, modal, session
experience, step
Custom events
A custom event takes its name from you, and not from the list above. Its event_type is
the name that you give it, so a query for it uses that name.
Two routes send one:
A data-picked-<interaction> attribute on an element. An element with
data-picked-click="add_to_cart" sends an add_to_cart event on a click.
The custom message of the template for Google Tag Manager, with a name of your choice.
A custom event always carries app and session. It also carries element, exception,
experience, feature_list, field_list, form, modal, order, product_list,
response_list, and step when the data is available.
Interaction types
An interaction event is a DOM event of the visitor. Its name is also an event_type value,
so a query for a click reads WHERE event_type = 'click'.
Element interactions
The SDK binds these listeners to an experience when the enableInteractionListeners option
of the analytics plugin names them. The option is off by default.
Interaction type
When it fires
Always attached
Attached when available
click
The visitor clicks an element.
element, feature_list, session
experience, step
rapid_click
The visitor clicks the same element many times in a short period.
element, feature_list, session
experience, step
right_click
The visitor opens the context menu on an element.
element, feature_list, session
experience, step
copy
The visitor copies a selection.
feature_list, session
element, experience, step
paste
The visitor copies text into a field.
feature_list, session
element, experience, step
drag
The visitor drags an element.
feature_list, session
element, experience, step
backspace
The visitor deletes a character in a field.
element, feature_list, session
experience, step
scroll
The visitor scrolls.
feature_list, session
element, experience, step
rapid_scroll
The visitor scrolls up and down fast.
feature_list, session
element, experience, step
mouse_shake
The visitor moves the pointer fast from side to side.
feature_list, session
experience, step
Page and network interactions
The SDK binds these listeners to the document when the enableDocumentListeners option of
the analytics plugin is true. The option is off by default.
Interaction type
When it fires
Always attached
Attached when available
page_visible
The page becomes visible, such as a return to the tab.
feature_list, session
experience, step
page_hidden
The page stops to be visible.
feature_list, session
experience, step
page_show
The browser shows the page, and also on a return from the cache.
feature_list, session
experience, step
page_hide
The browser hides the page before the visitor goes to a different page.
feature_list, session
experience, step
offline
The browser loses the network.
feature_list, session
experience, step
online
The browser gets the network back.
feature_list, session
experience, step
resize
The window changes size.
feature_list, session
experience, step
unload
The browser closes the document.
feature_list, session
experience, step
Interactions with no listener
The SDK declares these two types and sends none of them, because it binds no listener for
them. A query on one of them gives an empty result set.
Interaction type
When it fires
Always attached
Attached when available
back
Nothing sends it.
feature_list, session
experience, step
forward
Nothing sends it.
feature_list, session
experience, step
Schemas
Each context has a schema. Every schema also accepts a meta object for data of your own,
and keeps a property that the schema does not name. The field tables below do not repeat
meta.
Schema
What it describes
answer_list
The responses of a visitor, under the earlier name of response_list. The SDK attaches response_list.
app
The Picked project that the event belongs to.
cvly_funnel
The version of a Convincely funnel. The SDK attaches it for no event.
cvly_x
The Vercel deployment behind the site.
deployment
The deployment and the environment of the SDK.
element
The HTML element behind an interaction event.
event
The event itself. It is not a context: it holds the event type and the event_meta column.
exception
The reason for a failure or a validation error.
experience
The experience that the visitor is in.
feature_list
Each feature flag of the session, with the bucket of the visitor.
field_list
The fields of the current step, with their options.
form
The form behind a form event.
modal
The modal behind a modal event.
order
The order behind a purchase.
picked
The SDK version. The SDK attaches it for no event.
product_list
The products that the event is about.
question_list
The fields of a step, under the earlier name of field_list. The SDK attaches field_list.
recommendation_list
A list of recommended items. The SDK attaches it for no event.
response_list
The response of the visitor to each field.
session
The session, and each identifier that Picked has for it.
step
The step of the flow that the visitor is on.
app
Field
Type
Required
Description
project_id
string
Yes
The project ID.
deployment
Field
Type
Required
Description
env
string
Yes
The environment of the deployment.
id
string or null
No
The deployment ID.
sha
string or null
No
The Git hash of the deployment.
host
string or null
No
The host of the deployment.
cvly_x
Field
Type
Required
Description
vercel_deployment_id
string
Yes
The Vercel deployment ID.
vercel_env
string
Yes
The Vercel environment.
vercel_url
string
Yes
The URL of the Vercel deployment.
git_commit_sha
string or null
No
The Git hash of the deployment.
session
The session schema has no required field. A value is null until Picked has it.
Field
Type
Required
Description
id
string or null
No
The session ID.
is_user
boolean or null
No
True when Picked attributes the session to a known user.
gaid
string or null
No
The client ID from Google Analytics.
shopify_client_id
string or null
No
The Shopify client ID.
shopify_customer_id
string or null
No
The Shopify customer ID.
shopify_checkout_token
string or null
No
The Shopify checkout token.
fingerprintjs_visitor_id
string or null
No
The FingerprintJS visitor ID.
experience
Field
Type
Required
Description
id
string
Yes
The experience ID.
title
string
Yes
The experience title. It is experience_title in PickedQL.
type
string or null
No
The experience type.
step
Field
Type
Required
Description
id
string
Yes
The step ID. It is step_id in PickedQL.
title
string
Yes
The step title. It is step_title in PickedQL.
key
string or null
No
The stable key of the step. It does not change between versions.
feature_list
items is a list. Each item describes one feature flag of the session.
Field
Type
Required
Description
items
array
Yes
One entry for each feature flag.
items[].ab_feature
string
Yes
The feature ID.
items[].ab_name
string
Yes
The feature name. It is ab_feature_name in PickedQL.
items[].ab_key
string
Yes
The feature key.
items[].ab_bucket
boolean or string
Yes
The bucket of the visitor. It is ab_feature_value in PickedQL.
field_list
Field
Type
Required
Description
items
array
Yes
One entry for each field of the step.
items[].id
string
Yes
The field ID.
items[].type
string
Yes
The field type.
items[].label
string
Yes
The field label.
items[].options
array or null
No
The options that the field gives.
items[].options[].id
string
Yes
The option ID.
items[].options[].label
string
Yes
The option label.
items[].options[].value
string, number, boolean, object, array, or null
Yes
The value behind the option.
response_list
Field
Type
Required
Description
items
array
Yes
One entry for each field with a response.
items[].field_id
string
Yes
The ID of the field.
items[].values
array
Yes
The values that the visitor gave.
items[].values[].value
string, number, boolean, object, array, or null
Yes
One response value.
form
Field
Type
Required
Description
id
string
Yes
The form ID.
title
string or null
No
The form title.
modal
Field
Type
Required
Description
id
string
Yes
The modal ID.
title
string
Yes
The modal title.
element
Field
Type
Required
Description
node_type
string
Yes
The HTML tag name in lower case. It is unknown when the event has no element.
id
string or null
No
The id attribute of the element.
text
string or null
No
The text content of the element, to 255 characters.
label
string or null
No
The label of the element. It is the source of interaction_type in PickedQL.
exception
Field
Type
Required
Description
reason
string
Yes
The reason for the failure.
product_list
items follows the item format of GA4 Enhanced Ecommerce, so a variable in Google Tag
Manager maps onto it directly. Every item field accepts null.
Field
Type
Required
Description
items
array
Yes
One entry for each product.
title
string or null
No
The title of the list.
items[].item_id
string or null
No
The product ID. It is product_name in dim_product together with the name.
items[].item_name
string or null
No
The product name.
items[].item_brand
string or null
No
The brand.
items[].item_category
string or null
No
The category. item_category2 to item_category5 hold the deeper levels.
items[].item_variant
string or null
No
The variant.
items[].item_list_id
string or null
No
The ID of the list that the product came from.
items[].item_list_name
string or null
No
The name of that list.
items[].price
number or null
No
The price of one item.
items[].quantity
number or null
No
The quantity.
items[].discount
number or null
No
The discount on the item.
items[].currency
string or null
No
The currency code.
items[].coupon
string or null
No
The coupon code.
items[].affiliation
string or null
No
The store behind the order.
items[].index
number or null
No
The position of the product in the list.
items[].location_id
string or null
No
The location of the store.
items[].promotion_id
string or null
No
The promotion ID.
items[].promotion_name
string or null
No
The promotion name.
items[].creative_name
string or null
No
The creative name.
items[].creative_slot
string or null
No
The creative slot.
items[].in_stock
boolean or null
No
True when the product is in stock.
order
Field
Type
Required
Description
id
string
Yes
The order ID. It is order_id in PickedQL.
customer_id
string or null
No
The customer ID in the store.
checkout_token
string or null
No
The checkout token in the store.
cart_token
string or null
No
The cart token in the store.
event
The event schema wraps every event, and it is not a context.
Field
Type
Required
Description
type
string
Yes
The event type. It is event_type in PickedQL.
The meta object of this schema is the event_meta column in PickedQL.
recommendation_list
Field
Type
Required
Description
title
string
Yes
The title of the list.
items
array
Yes
One entry for each recommended item.
items[].sku
string
Yes
The SKU of the item.
items[].title
string
Yes
The title of the item.
question_list
question_list is the earlier name of field_list, and it has the same shape. On an item
and on an option, title takes the place of label.
Field
Type
Required
Description
items
array
Yes
One entry for each question.
items[].id
string
Yes
The question ID.
items[].type
string
Yes
The question type.
items[].title
string
Yes
The question title.
items[].options
array or null
No
The options that the question gives.
answer_list
answer_list is the earlier name of response_list, and it has the same shape.
