Formo defines some common fields (event type, timestamps, and more) across all API calls that make up the core event data structure. This guide covers the common and contextual fields in detail.

​
Common Fields

The Formo SDKs populate the required information automatically.

NameDatatypeRequiredDescription
typeString✓Captures the type of event. Values can be either identify, track, connect, signature, transaction, and others.
channelString✓Identifies the source of the event. Permitted values are mobile, web, server and sources.
versionString✓Version of the event spec.
project_idString✓Unique identification for the project in the database.
session_idString✓Privacy-friendly daily changing session identifier.
anonymous_idString✓Pseudo-identifier for the user in cases where userId is absent. Equivalent to a device ID.
user_idStringUnique identification for the user in the database.
addressStringUnique wallet address of the user.
eventStringCaptures the user action that you want to record.
contextObject✓Contains all additional user information.
propertiesObjectPasses all relevant information associated with the event.
timestampTimestamp✓Records the actual time (in UTC) when the event occurred. Make sure it conforms to the ISO 8601 date format yyyy-MM-ddTHH:mm:ss.SSSZ. For e.g., 2022-02-01T19:14:18.381Z.
message_idString✓Unique identification for the event.

​
Contextual Fields

Contextual fields give additional information about a particular event. The following table describes the available contextual fields.

NameDatatypeRequiredDescription
user_agentStringThe user agent of the device that you are tracking.
localeStringCaptures the language of the device.
locationStringGeographic location of the user.
timezoneStringCaptures the timezone of the user you are tracking.
referrerStringThe referrer URL where the user came from.
utm_sourceStringIdentifies which site sent the traffic.
utm_mediumStringIdentifies what type of link was used.
utm_campaignStringIdentifies a specific product promotion or strategic campaign.
utm_termStringIdentifies search terms.
utm_contentStringIdentifies what specifically was clicked to bring the user to the site.
refStringReferral code or identifier.
page_urlStringFull URL of the page.
page_pathStringPath component of the URL.
page_titleStringTitle of the page.
library_nameStringName of the SDK used to capture the event.
library_versionStringVersion of the SDK used to capture the event.

​
Sample Event

Here’s an example event with common and contextual fields included:

{
    "type": "page",
    "channel": "web",
    "version": "1",
    "project_id": "d5naNbBlqxSBXLuNa6zwc",
    "session_id": "117b982a451dc22edea6413b8e20958216c0a5b3baaa1d90699c42dbf4e74e33",    
    "anonymous_id": "c2bc0ebe-d852-49d1-9efd-e45744850ae0",
    "user_id": "a46e6878-1ed5-4a81-9185-83608df2fcb6",
    "address": "0x8e6ca77a7e044ba836a97beb796c124ca3a6a154",   
    "event": "FooBar", 
    "context": {
        "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36",
        "locale": "en-US",
        "location": "ID",
        "timezone": "Asia/Saigon",
        "referrer": "https://chatgpt.com/",
        "utm_source": "chatgpt.com",
        "utm_medium": "linkedin",
        "utm_campaign": "early-access",
        "utm_term": null,
        "utm_content": null,
        "ref": "vitalik.eth",
        "page_url": "https://www.estore.com/best-seller/1",
        "page_path": "/best-seller/1",
        "page_title": "The best sellers offered by EStore",
        "library_name": "Formo Web SDK",
        "library_version": "1.16.2"
    },
    "properties": {
        "name": "Best Seller",
        "category": "Docs",
        "url": "https://formo.so/faucets?utm_source=chatgpt.com",
        "path": "/best-seller/1",
        "hash": "#submit",
        "title": "The best sellers offered by EStore"
    },
    "message_id": "48555101eee2f44ac0f0632fcb7c7c9f6ce0012ae395ae79f8a0d515e4f5e41f",
    "timestamp": "2025-04-03 18:21:00"
}

Was this page helpful?

Suggest edits