Skip to main content

Tracking specific events

Tracking methods supported by the Golang Tracker at a glance:

FunctionDescription
TrackSelfDescribingEvent()Track a Snowplow custom unstructured event
TrackScreenView()Track the user viewing a screen within the application
TrackPageView()Track and record views of web pages.
TrackEcommerceTransaction()Track an ecommerce transaction
TrackStructEvent()Track a Snowplow custom structured event
TrackTiming()Track a timing event
note

All event structs require pointer values as a way of asserting properly whether or not a value has been passed that might have been required. As such there are three functions provided in helper package that allow you to inline pointer values:

  • NewString
  • NewInt64
  • NewFloat64

These all accept their respective raw value and return a pointer to this value.

To import the helper package:

import sphelp "github.com/snowplow/snowplow-golang-tracker/v3/pkg/common"

Commonโ€‹

All events are tracked with specific methods on the tracker instance, of the form TrackXXX(), where XXX is the name of the event to track.

Custom contextsโ€‹

In short, custom contexts let you add additional information about the circumstances surrounding an event in the form of an array of SelfDescribingJson structs ([]SelfDescribingJson). Each tracking method accepts an additional optional contexts parameter, which should be a list of contexts:

contextArray := []sp.SelfDescribingJson{}

If a visitor arrives on a page advertising a movie, the dictionary for a single custom context in the list might look like this:

contextArray := []sp.SelfDescribingJson{
*sp.InitSelfDescribingJson(
"iglu:com.acme_company/movie_poster/jsonschema/2-1-1",
map[string]interface{}{
"movie_name": "Solaris",
"poster_country": "JP",
},
),
}

This is how to fire a page view event with the above custom context:

tracker.TrackPageView(
sp.PageViewEvent{
PageUrl: sphelp.NewString("acme.com"),
Contexts: contextArray,
},
)

Note that even though there is only one custom context attached to the event, it still needs to be placed in an array.

Optional timestamp argumentโ€‹

Each Track...() method supports an optional timestamp argument; this allows you to manually override the timestamp attached to this event. The timestamp should be in milliseconds since the Unix epoch.

If you do not pass this timestamp in as an argument, then the Golang Tracker will use the current time to be the timestamp for the event.

Here is an example tracking a structured event and supplying the optional timestamp argument:

tracker.TrackStructEvent(sp.StructuredEvent{
Category: sphelp.NewString("some category"),
Action: sphelp.NewString("some action"),
Timestamp: sphelp.NewInt64(1368725287000),
})

Optional true-timestamp argumentโ€‹

Each Track...() method supports an optional true-timestamp argument; this allows you to provide the true-timestamp attached to this event to help with the timing of events in multiple timezones. The timestamp should be in milliseconds since the Unix epoch.

Here is an example tracking a structured event and supplying the optional true-timestamp argument:

tracker.TrackStructEvent(sp.StructuredEvent{
Category: sphelp.NewString("some category"),
Action: sphelp.NewString("some action"),
TrueTimestamp: sphelp.NewInt64(1368725287000),
})

Optional event ID argumentโ€‹

Each Track...() method supports an optional event id argument; this allows you to manually override the event ID attached to this event. The event ID should be a valid version 4 UUID string.

Here is an example tracking a structured event and supplying the optional event ID argument:

tracker.TrackStructEvent(sp.StructuredEvent{
Category: sphelp.NewString("some category"),
Action: sphelp.NewString("some action"),
EventId: sphelp.NewString("486820fb-e722-4311-b33d-d2f319b511f6"),
})

Optional Subject argumentโ€‹

Each Track...() method supports an optional Subject argument; this allows you to manually override the Subject information that is usually pulled from the Tracker object.

Here is an example of tracking a Page View event and supplying the optional Subject argument:

eventSubject := sp.InitSubject()
eventSubject.SetUserId("987654321")

tracker.TrackPageView(sp.PageViewEvent{
PageUrl: sphelp.NewString("acme.com"),
Subject: eventSubject,
})

Track SelfDescribing/Unstructured events with TrackSelfDescribingEvent()โ€‹

Use TrackSelfDescribingEvent() to track a custom event which consists of a name and an unstructured set of properties. This is useful when:

  • You want to track event types which are proprietary/specific to your business (i.e. not already part of Snowplow), or
  • You want to track events which have unpredictable or frequently changing properties

The arguments are as follows:

ArgumentDescriptionRequired?Validation
EventThe properties of the eventYes*SelfDescribingJson
TimestampWhen the event occurredNo*int64
EventIdThe event IDNo*string
TrueTimestampThe true time of eventNo*int64
ContextsCustom contexts for the eventNo[]SelfDescribingJson
SubjectEvent specific SubjectNoSubject

Example:

// Create a data map
data := map[string]interface{}{
"level": 5,
"saveId": "ju302",
"hardMode": true,
}

// Create a new SelfDescribingJson
sdj := sp.InitSelfDescribingJson("iglu:com.example_company/save-game/jsonschema/1-0-2", data)

tracker.TrackSelfDescribingEvent(sp.SelfDescribingEvent{
Event: sdj,
})

For more on JSON schema, see the blog post.

Track screen views with TrackScreenView()โ€‹

Use TrackScreenView() to track a user viewing a screen (or equivalent) within your app:

ArgumentDescriptionRequired?Type
NameHuman-readable name for this screenNo*string
IdUnique identifier for this screenNo*string
TimestampWhen the event occurredNo*int64
EventIdThe event IDNo*string
TrueTimestampThe true time of eventNo*int64
ContextsCustom contexts for the eventNo[]SelfDescribingJson
SubjectEvent specific SubjectNoSubject

Although name and id are not individually required, at least one must be provided or the event will fail validation.

Example:

tracker.TrackScreenView(sp.ScreenViewEvent{
Id: sphelp.NewString("Screen ID"),
})

Track pageviews with TrackPageView()โ€‹

Use TrackPageView() to track a user viewing a page within your app:

ArgumentDescriptionRequired?Validation
PageUrlThe URL of the pageYes*string
PageTitleThe title of the pageNo*string
ReferrerThe address which linked to the pageNo*string
TimestampWhen the event occurredNo*int64
EventIdThe event IDNo*string
TrueTimestampThe true time of eventNo*int64
ContextsCustom contexts for the eventNo[]SelfDescribingJson
SubjectEvent specific SubjectNoSubject

Example:

tracker.TrackPageView(sp.PageViewEvent{
PageUrl: sphelp.NewString("acme.com"),
})

Track ecommerce transactions with TrackEcommerceTransaction()โ€‹

Use TrackEcommerceTransaction() to track an ecommerce transaction:

ArgumentDescriptionRequired?Validation
OrderIdID of the eCommerce transactionYes*string
TotalValueTotal transaction valueYes*float64
AffiliationTransaction affiliationNo*string
TaxValueTransaction tax valueNo*float64
ShippingDelivery cost chargedNo*float64
CityDelivery address cityNo*string
StateDelivery address stateNo*string
CountryDelivery address countryNo*string
CurrencyTransaction currencyNo*string
ItemsItems in the transactionYes[]EcommerceTransactionItemEvent
TimestampWhen the event occurredNo*int64
EventIdThe event IDNo*string
TrueTimestampThe true time of eventNo*int64
ContextsCustom contexts for the eventNo[]SelfDescribingJson
SubjectEvent specific SubjectNoSubject

The items argument is an Array of TransactionItems. TrackEcommerceTransaction fires multiple events: one transaction event for the transaction as a whole, and one transaction item event for each element of the Items list. Each transaction item event will have the same timestamp, true timestamp, order ID, and currency as the main transaction event.

These are the fields with which a TransactionItem can be created.

FieldDescriptionRequired?Validation
SkuItem SKUYes*string
PriceItem priceYes*float64
QuantityItem quantityYes*int64
NameItem nameNo*string
CategoryItem categoryNo*string
EventIdThe event IDNo*string
ContextsCustom contexts for the eventNo[]SelfDescribingJson
SubjectEvent specific SubjectNoSubject

Example of tracking a transaction containing two items:

items := []sp.EcommerceTransactionItemEvent{
sp.EcommerceTransactionItemEvent{
Sku: sphelp.NewString("pbz0026"),
Price: sphelp.NewFloat64(20),
Quantity: sphelp.NewInt64(1),
},
sp.EcommerceTransactionItemEvent{
Sku: sphelp.NewString("pbz0038"),
Price: sphelp.NewFloat64(15),
Quantity: sphelp.NewInt64(1),
Name: sphelp.NewString("red hat"),
Category: sphelp.NewString("menswear"),
},
}

tracker.TrackEcommerceTransaction(sp.EcommerceTransactionEvent{
OrderId: sphelp.NewString("6a8078be"),
TotalValue: sphelp.NewFloat64(35),
Affiliation: sphelp.NewString("some-affiliation"),
TaxValue: sphelp.NewFloat64(6.12),
Shipping: sphelp.NewFloat64(30),
City: sphelp.NewString("Dijon"),
State: sphelp.NewString("Bourgogne"),
Country: sphelp.NewString("France"),
Currency: sphelp.NewString("EUR"),
Items: items,
})

Track structured events with TrackStructEvent()โ€‹

Use TrackStructEvent() to track a custom event happening in your app which fits the Google Analytics-style structure of having up to five fields (with only the first two required):

ArgumentDescriptionRequired?Validation
CategoryThe grouping of structured events which this action belongs toYes*string
ActionDefines the type of user interaction which this event involvesYes*string
LabelA string to provide additional dimensions to the event dataNo*string
PropertyA string describing the object or the action performed on itNo*string
ValueA value to provide numerical data about the eventNo*float64
TimestampWhen the event occurredNo*int64
EventIdThe event IDNo*string
TrueTimestampThe true time of eventNo*int64
ContextsCustom contexts for the eventNo[]SelfDescribingJson
SubjectEvent specific SubjectNoSubject

Example:

tracker.TrackStructEvent(sp.StructuredEvent{
Category: sphelp.NewString("shop"),
Action: sphelp.NewString("add-to-basket"),
Property: sphelp.NewString("pcs"),
Value: sphelp.NewFloat64(2),
})

Track timing events with TrackTiming()โ€‹

Use TrackTiming() to track a timing event.

The arguments are as follows:

ArgumentDescriptionRequired?Validation
CategoryThe category of the eventYes*string
VariableThe variable of the eventYes*string
TimingThe timing of the eventYes*int64
LabelThe label of the eventNo*string
TimestampWhen the event occurredNo*int64
EventIdThe event IDNo*string
TrueTimestampThe true time of eventNo*int64
ContextsCustom contexts for the eventNo[]SelfDescribingJson
SubjectEvent specific SubjectNoSubject

Example:

tracker.TrackTiming(sp.TimingEvent{
Category: sphelp.NewString("Timing Category"),
Variable: sphelp.NewString("Some var"),
Timing: sphelp.NewInt64(124578),
})
Was this page helpful?