trackAction

Observable field that fires when the SDK emits an analytics event classified as an action — meaning an active user interaction.

Description

Emits an analytics payload each time the SDK fires an engage or action analytics event. This includes panel engage events, module engage and dismiss events, overlay engage events, and any analytics event explicitly designated as an action.

Use this field alongside trackImpression to receive the full analytics event stream from the SDK and forward it to your own analytics platform.

Type

assocArray

Usage

m.lib.observeField("trackAction", "onTrackAction")

function onTrackAction(event as Object)
    payload = event.getData()
    if payload = invalid then return

    metadata = payload.metadata
    eventName = metadata?.event_name

    ' Forward to your analytics platform
    myAnalytics.trackAction(eventName, metadata)
end function

Data Structure

The payload shape depends on whether the event originated from a backend analytics event or a client-specific event.

Backend analytics events

Backend events (panel, session, module, overlay) arrive as the full analytics beacon:

Field	Type	Description
e0_kingdom	string	The event kingdom (e.g., "panel", "overlay", "module").
e1_phylum	string	The event phylum (e.g., "engage").
e2_class	string	The panel or overlay type.
e3_order	string	Panel or overlay ID.
e4_family	string	Panel or overlay name.
e5_genus	string	Sub-classification (may be empty).
e6_species	string	Instance identifier (may be empty).
metadata	assocArray	Event-specific metadata fields.

The metadata object contains fields specific to the event, such as event, card, game_state, and any host_metadata fields the event declares (for example, overlay_event, overlay_id, and overlay_name on overlay events).

Client-specific events

Events with no backend taxonomy (such as client-specific named events) arrive without the e0–e6 fields:

Field	Type	Description
metadata	assocArray	Contains event_name (the event identifier) plus event-specific fields.

Example

sub setupAnalyticsObservers()
    m.lib.observeField("trackAction", "onTrackAction")
    m.lib.observeField("trackImpression", "onTrackImpression")
end sub

function onTrackAction(event as Object)
    payload = event.getData()
    if payload = invalid then return

    metadata = payload.metadata
    eventName = metadata?.event_name

    ' A backend event carries both taxonomy and metadata
    if payload.e0_kingdom <> invalid
        kingdom = payload.e0_kingdom
        phylum = payload.e1_phylum
        panelClass = payload.e2_class
        print "Analytics action: " + kingdom + ":" + phylum + ":" + panelClass
    else
        ' A client-specific event carries only metadata
        print "Analytics action: " + as.string(eventName)
    end if

    ' Forward to your analytics platform
    myAnalytics.trackAction(eventName, metadata)
end function

Notes

• Fires for active user interactions: panel engages, module engage and dismiss events, overlay engage events, and other events designated as actions.
• Observe trackImpression for passive lifecycle events such as views, session boundaries, and dismissals.
• Distinct from trackingEvent, which emits the raw internal analytics payload before it is forwarded to the Maestro backend.
• The metadata object may contain nested values (for example, overlay_data on overlay events).
• For overlay events, the metadata object includes overlay_event, overlay_id, and overlay_name fields.

Related

• trackImpression
• trackingEvent
• Overlay Integration Guide