track()

The track() method records a custom event with a name and optional properties. Use it to capture user actions, conversions, and business events.

Syntax

iOS (Swift)

Datafly.shared.track(_ event: String, properties: [String: Any]? = nil)

Android (Kotlin)

Datafly.track(event: String, properties: Map<String, Any>? = null)

React Native / Cordova

DataflySignal.track(eventName, properties?)

Flutter

await DataflySignal.track(event, properties: {...})

.NET MAUI

DataflySignal.Track(eventName, properties)

Parameters

Parameter	Type	Required	Description
`event`	`String`	Yes	The name of the event (e.g., `"purchase"`)
`properties`	`Dictionary/Map`	No	Key-value pairs describing the event

Basic usage

// iOS
Datafly.shared.track("sign_up", properties: ["method": "email"])
 
// Android
Datafly.track("sign_up", mapOf("method" to "email"))
 
// React Native
DataflySignal.track("sign_up", { method: "email" });

E-commerce example

Datafly.shared.track("purchase", properties: [
    "transaction_id": "ORD-12345",
    "value": 99.99,
    "currency": "GBP",
    "items": [
        ["item_id": "SKU-001", "item_name": "Running Shoes", "price": 79.99, "quantity": 1],
        ["item_id": "SKU-042", "item_name": "Sport Socks", "price": 9.99, "quantity": 2],
    ],
    "coupon": "SUMMER20",
    "tax": 8.00,
    "shipping": 5.99,
])

Standard e-commerce events

Datafly uses GA4-compatible event names. Signal’s blueprints automatically map these to vendor-specific formats during server-side delivery.

Event name	Description	Key properties
`view_item`	User viewed a product	`item_id`, `item_name`, `price`, `currency`
`add_to_cart`	User added to cart	`item_id`, `item_name`, `price`, `quantity`
`begin_checkout`	User started checkout	`value`, `currency`, `items[]`
`purchase`	User completed purchase	`transaction_id`, `value`, `currency`, `items[]`
`search`	User searched	`search_term`
`sign_up`	User registered	`method`
`login`	User logged in	`method`
`generate_lead`	Lead created	`value`, `currency`

Use snake_case for event names and property names. These match GA4 conventions and are automatically mapped to vendor-specific formats by Signal’s blueprints.

Event payload

A track() call produces an event with type: "track":

{
  "type": "track",
  "event": "purchase",
  "anonymousId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "userId": "user-123",
  "properties": {
    "transaction_id": "ORD-12345",
    "value": 99.99,
    "currency": "GBP"
  },
  "context": {
    "device": { "manufacturer": "Apple", "model": "iPhone15,1", "os": "iOS", "os_version": "17.0" },
    "screen": { "width": 1170, "height": 2532, "density": 3.0 },
    "session": { "id": 1712498234567, "number": 3, "is_new": false },
    "locale": "en-GB",
    "timezone": "Europe/London",
    "library": { "name": "@datafly/ios", "version": "1.0.0" }
  },
  "timestamp": "2026-04-06T14:22:00.000Z",
  "messageId": "df-b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}

⚠️

Do not include PII (email, phone, name) in track() properties. Use identify() instead — Signal hashes PII server-side before delivering to vendors.

Capacitor (Ionic)screen()