Universal Collect Documentation

Collect as you breath

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.

Hits

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

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

Type

Required for all hit types

This argument refers to the type of hit.

ParameterValue TypeDefault ValueMax LengthSupported hit types
tstringNoneNoneall
  • 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).

ParameterValue TypeDefault ValueMax LengthSupported hit types
cidstringNone32 Bytesall
  • 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
vidstringNone50 Bytesall
  • 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.

ParameterValue TypeDefault ValueMax Length
dsstringAPP10 Bytes
  • 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
uipstringNone45 Bytesall
  • 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
srstringNone20 Bytesall
  • Example value: 800x600
  • Example usage: sr=800x600

Page Title

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

ParameterValue TypeDefault ValueMax LengthSupported hit types
ptstringNone1500 Bytesall

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

User Language

Optional for all hit types

This argument refers to the user's language.

ParameterValue TypeDefault ValueMax LengthSupported hit types
ulstringNone20 Bytesall
  • 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
dlstringNone2048 Bytesall
  • 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
cstIntegerNoneNoneall
  • 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
snIntegerNoneNoneall
  • 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

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

Implementation example

curl -X POST \
  https://ariane.abtasty.com \
  -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

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

Implementation example

curl -X POST \
  https://ariane.abtasty.com \
  -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 required common 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
ecstringNone150 BytesEVENT
  • 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
eastringNone500 BytesEVENT
  • Example value: newsletterSubscription
  • Example usage: ea=newsletterSubscription
Event Label

Optional

This argument is a supplementary description of your event. The value is not yet available inside our reporting.

ParameterValue TypeDefault ValueMax LengthSupported hit types
elstringNone500 BytesEVENT
  • 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 useful when there's a monetary value associated with an event.

For example, if you earn 10 to 100 euros depending on the quality of lead generated, you can add this information to your hits to monitor total and average value inside the reporting.

❗️

The ev must be non-negative.

ParameterValue TypeDefault ValueMax LengthSupported hit types
evintegerNone500 BytesEVENT
  • Example value: 1
  • Example usage: ev=1

Implementation example

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": "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 required common 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 ID tid values must be unique for each transaction.

ParameterValue TypeDefault ValueMax LengthSupported hit types
tidstringNone500 BytesTRANSACTION, ITEM

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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
tastringNone500 BytesTRANSACTION

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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
trfloat0NoneTRANSACTION

Example value: 15.47
Example usage: tr=15.47

Transaction Shipping

Optional

This argument specifies the total shipping costs of a transaction.

ParameterValue TypeDefault ValueMax LengthSupported hit types
tsfloat0NoneTRANSACTION

Example value: 3.50
Example usage: ts=3.50

Transaction Tax

Optional

This argument specifies the total tax collected in a transaction.

ParameterValue TypeDefault ValueMax LengthSupported hit types
ttfloat0NoneTRANSACTION

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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
tcstringNone500 BytesTRANSACTION

Example value: EUR
Example usage: tc=EUR

Transaction Coupon Code

Optional

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

ParameterValue TypeDefault ValueMax LengthSupported hit types
tccstringNone10 BytesTRANSACTION

Example value: coupon
Example usage: tcc=coupon

Payment Method

Optional

This argument indicates the payment method used in a transaction.

ParameterValue TypeDefault ValueMax LengthSupported hit types
pmstringNone10 BytesTRANSACTION

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

Shipping Method

Optional

This argument indicates the shipping method used in a transaction.

ParameterValue TypeDefault ValueMax LengthSupported hit types
smstringNone10 BytesTRANSACTION

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

Item Count Number

Optional

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

ParameterValue TypeDefault ValueMax LengthSupported hit types
icnintNoneNoneTRANSACTION

Example value: 12
Example usage: icn=12

Implementation example

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": "18100217380532936",
  "ds": "APP"
}'

Item

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

:::caution
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 required Common 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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
tidstringNone500 BytesTRANSACTION, ITEM

Example value: OD564
Example usage: tid=OD564

Item Name

Required

This argument specifies the name of an item.

ParameterValue TypeDefault ValueMax LengthSupported hit types
instringNone500 BytesITEM

Example value: Shoe
Example usage: in=Shoe

Item Code

Required

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

ParameterValue TypeDefault ValueMax LengthSupported hit types
icstringNone500 BytesITEM

Example value: SKU47
Example usage: ic=SKU47

Item Price

Optional

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

ParameterValue TypeDefault ValueMax LengthSupported hit types
ipfloat0NoneITEM

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.

ParameterValue TypeDefault ValueMax LengthSupported hit types
iqinteger0NoneITEM

Example value: 4
Example usage: iq=4

Item Category

Optional

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

ParameterValue TypeDefault ValueMax LengthSupported hit types
ivstringNone500 BytesITEM

Example value: Blue
Example usage: iv=Blue

Implementation example

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": "18100217380532936",
  "ds": "APP"
}'
}'

📘

Reports availability

The ITEM hit isn't available yet in the Flagship reports view.

Hit validation

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


Did this page help you?