Universal Collect Documentation

Overview

Flagship’s Universal Collect protocol provides a unified hit format to send data back to Flagship for reporting purposes. The format of the hit is based on the Google Analytics measurement protocol.

Universal Collect is compatible with both Decision API implementations (for both server-side and client-side applications) and Flagship SDKs.

🚧

Heads Up

In order to see your events in the Flagship reporting interface, the visitor first needs to be assigned to a use case.

Common arguments

There are certain arguments that are required for every hit type. You should get to know them before reading into hit-specific arguments.

• Common Arguments list

Hits

Learn more about the specific arguments and rules associated with each hit type by clicking on the hit names below.

• Pageview
• Screenview
• Event
• Transaction
• Item

Common Arguments list

These arguments can be sent with any type of hit. Including more data with your hit will yield more actionable reports so you can more clearly identify what works, what doesn't work, and where you can drill down further.

Summary

• Required for all hit types:

  • Type
  • Environment ID
  • Visitor ID
  • Data Source

• Required for Screenview & Pageview hits only:

  • Document Location URL

• Optional for all hit types

  • User IP (optional)
  • Screen Resolution (optional)
  • User Language (optional)
  • Current Session Timestamp (optional)
  • Session Number (optional)

Type

Required for all hit types

This argument refers to the type of hit.

• CAMPAIGN
• PAGEVIEW (hit documentation)
• SCREENVIEW (hit documentation)
• EVENT (hit documentation)
• ITEM (hit documentation)
• TRANSACTION (hit documentation)

• Example value: SCREENVIEW
• Example usage: t=SCREENVIEW

📘

CAMPAIGN hit

You might see some CAMPAIGN hits when browsing your network.
They are automatically sent when:

• You call the /campaign Decision API endpoint with the trigger_hit parameter not set to false
• You call the /activate Decision API endpoint
• You use one of the activate method available in SDKs (with API or Bucketing mode)

Environment ID

Required for all hit types

This argument refers to the unique ID of the environment in Flagship (prod or preprod).

• Example value: bmg9e8r7serg0gvp30s0
• Example usage: cid=bmg9e8r7serg0gvp30s0

Visitor ID

Required for all hit types

This argument refers to the unique ID associated with the application user or website visitor.

• Example value: user1234354
• Example usage: vid=user1234354

Data Source

Required for all hit types

This argument refers to the data source type. The value should be set to APP.

• Required value: APP
• Required usage: ds=APP

User IP

Optional for all hit types

This argument refers to the IP address of the user. This should be a valid IP address in IPv4 or IPv6 format. It will always be anonymized.

• Example value: 52.311.94.68
• Example usage: uip=52.211.94.68

Screen Resolution

Optional for all hit types

This argument refers to the the screen resolution in pixels.

• Example value: 800x600
• Example usage: sr=800x600

Page Title

This argument refers to the title of the page or document.

— Example value: Settings
— Example usage: pt=Settings

User Language

Optional for all hit types

This argument refers to the user's language.

• Example value: en-us
• Example usage: ul=en-us

Document Location URL

Required for Screenview & Pageview hit types.

This argument refers to the URL of the page, or the Screen Name of the app, at the moment the hit is sent.

📘

SCREENVIEW hit specificity

For SCREENVIEW, the dl can be equal to any string value.

📘

PAGEVIEW hit specificity

For PAGEVIEW, the value must be a valid URL. Otherwise the hit will be rejected.
Also, our server will compute more information from this URL, such as domain name, path, parameters, etc.

• Example value: https://abtastylab.com/b0711162425441fb679dc41b98f052ab/
• Example usage: dl=https%3A%2F%2Fabtastylab.com%2Fb0711162425441fb679dc41b98f052ab%2F

Current Session Timestamp

Optional for all hit types

This argument indicates when the current session was started in Unix Epoch time.

• Example value: 1522053173006
• Example usage: cst=1522053173006

Session Number

Optional for all hit types

This argument indicates the number of sessions the current visitor has logged, including the current session.

• Example value: 6
• Example usage: sn=6

Hits

Screenview

This hit should be sent every time the visitor lands on a new screen on your application.

Arguments

• SCREENVIEW hits must implement the Document Location URL in addition to the required common arguments
• Common argument Type (t) must be set to SCREENVIEW

That's it! There are no other hit-specific arguements for this hit type.

Implementation example

📘

Previous endpoint note

The previous endpoint is still active: https://ariane.abtasty.com

curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "{{environmentId}}",
  "dl": "HomeScreen",
  "t": "SCREENVIEW",
  "vid": "{{visitorId}}",
  "ds":"APP"
}'

Pageview

This hit should be sent every time the visitor lands on a new page on your website.

Arguments

• PAGEVIEW hits must implement the Document Location URL in addition to the required common arguments
• Common argument Type (t) must be set to PAGEVIEW

That's it! There are no other hit-specific arguements for this hit type.

Implementation example

📘

Previous endpoint note

The previous endpoint is still active: https://ariane.abtasty.com

curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "{{environmentId}}",
  "dl": "https://www.abtasty.com",
  "t": "PAGEVIEW",
  "vid": "{{visitorId}}",
  "ds":"APP"
}'

Event

This hit type can be used to measure any events you may be interested in, from element clicks to newsletter subscriptions.

Arguments

• EVENT hits must implement the requiredcommon arguments
• Common argument Type (t) must be set to EVENT

Event Category

Required for EVENT hit type

This argument categorizes the event and helps us understand what you want to retrieve inside the reporting.

• Example value: Action Tracking
• Example usage: ec="Action Tracking"

❗️

The ec must be equal to Action Tracking or User Engagement

Event Action

Required for EVENT hit type

This argument corresponds to the KPI name you will be able to select inside the Flagship dashboard reporting.

• Example value: newsletterSubscription
• Example usage: ea=newsletterSubscription

Event Label

Optional

This argument is a supplementary description of your event.

• Example value: contains status of user newsletter mode
• Example usage: el=contains status of user newsletter mode

Event Value

Optional

The Event Value can be used to evaluate user interactions with individual site objects or content items.

For example, each new registration for a newsletter gets an event value.

❗️

The ev must be non-negative.
The ev must be an integer (It won't work with float)

• Example value: 1
• Example usage: ev=1

Implementation example

📘

Previous endpoint note

The previous endpoint is still active: https://ariane.abtasty.com

curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "dl": "https://react-ecommerce-demo.internal.flagship.io/",
  "ea": "newsletterSubscription",
  "ec": "Action Tracking",
  "el": "optin",
  "ev": 1,
  "t": "EVENT",
  "vid": "18100217380532936",
  "ds": "APP"
}'

Transaction

A transaction hit should be manually configured to be sent each time a visitor completes a transaction.

❗️

Do not send TRANSACTION and EVENT hits with the same ta and ea parameter values.

A transaction can be linked to other ITEM hits to specify the products of the transaction (see item event documentation).

Arguments

• TRANSACTION hits must implement the requiredcommon arguments
• Common argument Type (t) must be set to TRANSACTION

Transaction ID

Required for TRANSACTION hit type and for ITEM hit type when triggered on confirmation page.

Transaction IDtid values must be unique for each transaction.

Example value: OD564
Example usage: tid=OD564

Transaction Affiliation

Required

This argument corresponds to the KPI name you will be able to select inside the Flagship dashboard reporting.

Example value: Purchase
Example usage: ta=Purchase

Transaction Revenue

Optional

This argument specifies the total revenue associated with a transaction. This value should include any supplementary costs such as shipping or taxes.

Example value: 15.47
Example usage: tr=15.47

Transaction Shipping

Optional

This argument specifies the total shipping costs of a transaction.

Example value: 3.50
Example usage: ts=3.50

Transaction Tax

Optional

This argument specifies the total tax collected in a transaction.

Example value: 2.60
Example usage: tt=2.60

Transaction Currency

Optional

When present, this argument indicates the local currency for all the currency values in a transaction. The value should be a valid ISO 4217 currency code.

Example value: EUR
Example usage: tc=EUR

Transaction Coupon Code

Optional

This argument refers to the coupon or discount code associated with a transaction.

Example value: coupon
Example usage: tcc=coupon

Payment Method

Optional

This argument indicates the payment method used in a transaction.

Example value: Paypal
Example usage: pm="Paypal"

Shipping Method

Optional

This argument indicates the shipping method used in a transaction.

Example value: express
Example usage: sm="express"

Item Count Number

Optional

This argument indicates the number of items included in a transaction.

Example value: 12
Example usage: icn=12

Implementation example

📘

Previous endpoint note

The previous endpoint is still active: https://ariane.abtasty.com

curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "icn": 12,
  "pm": "Paypal",
  "sm": "Fedex",
  "t": "TRANSACTION",
  "ta": "Purchase",
  "tc": "EUR",
  "tcc": "Coupon",
  "tid": "OD564",
  "tr": 15.47,
  "ts": 3.5,
  "tt": 2.6,
  "vid": "18100217380532936",
  "ds": "APP"
}'

Item

Items usually represent individual products. ITEM hits must be associated with a TRANSACTION.

🚧

Make sure the TRANSACTION hit that corresponds to the tid argument is triggered before the ITEM hit, otherwise the hits will not be consolidated.

Arguments

• An ITEM hit must implement the requiredCommon Arguments
• Common argument Type (t) must be set to ITEM.

Transaction ID

Required for ITEM and TRANSACTION hit types

This argument allows an item to be linked to a transaction with a matching Transaction ID tid.

Example value: OD564
Example usage: tid=OD564

Item Name

Required

This argument specifies the name of an item.

Example value: Shoe
Example usage: in=Shoe

Item Code

Required

This argument specifies an item's SKU or product bar code.

Example value: SKU47
Example usage: ic=SKU47

Item Price

Optional

This argument specifies the price for a single unit of an item.

Example value: 3.50
Example usage: ip=3.50

Item Quantity

Optional

This argument indicates the number of units of an item that are purchased.

Example value: 4
Example usage: iq=4

Item Category

Optional

This argument specifies the product category that an item belongs to.

Example value: Blue
Example usage: iv=Blue

Implementation example

📘

Previous endpoint note

The previous endpoint is still active: https://ariane.abtasty.com

curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "dl": "https://react-ecommerce-demo.internal.flagship.io/",
  "ic": "SKU47",
  "in": "Shoe",
  "ip": 3.5,
  "iq": 4,
  "iv": "Blue",
  "t": "ITEM",
  "tid": "OD564",
  "vid": "18100217380532936",
  "ds": "APP"
}'

Experience Continuity

In case you're using Experience Continuity with the Decision API only and you're directly doing POST call to the Universal Collect, you have to pass the cuid parameter corresponding to the authenticated visitorId.

Implementation example

🚧

Make sure that the Experience Continuity option is enabled on the Flagship platform before using those methods.

📘

Previous endpoint note

The previous endpoint is still active: https://ariane.abtasty.com

curl -X POST \
  https://events.flagship.io \
  -H 'content-type: application/json' \
  -d '{
  "cid": "{{environmentId}}",
  "dl": "https://www.abtasty.com",
  "t": "PAGEVIEW",
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds":"APP"
}'

curl -X POST \
  https://ariane.abtasty.com \
  -H 'content-type: application/json' \
  -d '{
  "cid": "{{environmentId}}",
  "dl": "HomeScreen",
  "t": "SCREENVIEW",
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds":"APP"
}'

curl -X POST \
  https://ariane.abtasty.com \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "dl": "https://react-ecommerce-demo.internal.flagship.io/",
  "ea": "newsletterSubscription",
  "ec": "Action Tracking",
  "el": "optin",
  "ev": 1,
  "t": "EVENT",
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds": "APP"
}'

curl -X POST \
  https://ariane.abtasty.com \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "icn": 12,
  "pm": "Paypal",
  "sm": "Fedex",
  "t": "TRANSACTION",
  "ta": "Purchase",
  "tc": "EUR",
  "tcc": "Coupon",
  "tid": "OD564",
  "tr": 15.47,
  "ts": 3.5,
  "tt": 2.6,
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds": "APP"
}'

curl -X POST \
  https://ariane.abtasty.com \
  -H 'content-type: application/json' \
  -d '{
  "cid": "1234567890azertyuiop",
  "dl": "https://react-ecommerce-demo.internal.flagship.io/",
  "ic": "SKU47",
  "in": "Shoe",
  "ip": 3.5,
  "iq": 4,
  "iv": "Blue",
  "t": "ITEM",
  "tid": "OD564",
  "vid": "anonymousID123",
  "cuid": "18100217380532936",
  "ds": "APP"
}'

Hit validation

You can use this tool to help you validate the hits you send to Flagship