Skip to main content

Events and attributes tracking

There are two types of information that can be tracked (or logged, or fired) to better understand user behavior: events and attributes:

  • event refers to something that has occurred at a random time
  • attribute defines the state of an object, user, or device at specific time

The PAPulse SDK categorizes events into different types, including builtin, standard, and custom. For more detailed information, please refer to the Fundamentals. The SDK provides various API approaches to track these events accordingly.

Danger Zone

Please note that the logging of events and attributes will take place only after the session has been initiated by calling the PAAnalytics.start() method. If you try to log any event or attribute before making that call, the SDK will postpone further processing until it is properly initialized.

Logging custom events​

Event is for marking when something happens, it has event_name and optionally attached to it a dictionary of additional fields called data. Most straightforward way to log an custom event is by calling:

PAAnalytics.logEvent(event_name)

When there is data dictionary with parameters associated with an event, you can use the following call:

PAAnalytics.logEvent(event_name, data: data)

When an event is not instantaneous and takes some time to complete, you can specify the duration using the following call:

PAAnalytics.logEvent(event_name, data: data, duration: duration)

Depending on your intention, the logged event can be treated as either independent or aggregated into a specific group known as a flow. You can include the logged event into a desired group (flow) by invoking the following call:

PAAnalytics.logEvent(event_name, data: data, duration: duration, actions: actions)
Keep in mind

Before logging a new event, make sure that the event name and corresponding structure for data parameters are defined and approved in the dashboard Picsart Tools. Otherwise, the analytics backend will ignore this event.

Keep in mind

If you use Swift, all these methods use optional parameters with default values

Logging UIKit standard events​

The PAPulse SDK provides a convenient way to automatically track UIKit-related events such as pa_open and pa_click out of the box. You can find more details in the Auto-events and Flow section. By calling UIViewController.enableAutoTracking() or UIButton.enableAutoTracking(), the SDK will automatically log pa_open for all UIViewControllers and pa_click for configured instances of UIKit controls.

If this built-in functionality doesn't meet all your requirements, such as tracking the appearance of a floating tab bar, the SDK offers various methods to track the corresponding pa_open event. 

PAAnalytics.logOpen(elementData: elementData)
PAAnalytics.logOpen(additionalProperties: additionalProperties, elementData: elementData)
PAAnalytics.logOpen(additionalProperties: additionalProperties, additionalIDs: additionalIDs, elementData: elementData)
PAAnalytics.logOpen(additionalProperties: additionalProperties, additionalIDs: additionalIDs, elementData: elementData, actions: actions)

or if you need to track pa_click event explicitly from a specific location in your code

PAAnalytics.logClick(elementData: elementData)
PAAnalytics.logClick(additionalProperties: additionalProperties, elementData: elementData)
PAAnalytics.logClick(additionalProperties: additionalProperties, additionalIDs: additionalIDs, elementData: elementData)
PAAnalytics.logClick(additionalProperties: additionalProperties, additionalIDs: additionalIDs, elementData: elementData, actions: actions)

where:

  • additionalProperties are key-value pairs that will be included in resulting event's data.additionalProperties field.
  • additionalIDs are key-value pairs that will be included in resulting event's data.additionalIDs field.
  • elementData is information about the element that is source of this event that will be included in resulting event's data.element field.
  • actions are actions that should be done along this event, like starting or ending a flow.

Logging attributes​

Attribute is only one value connected to attribute_name with type PAAnalyticsAttributeType. PAAnalyticsAttributeType is an enum, with possible values of .default or .increment.

By default attributes logging feature is disabled. It means all external and internal calls as logAttribute are ignored. If you have guaranteed backend support for this feature, you can enable or disable attributes logging explicitly (see configSetAttributeLoggingEnabled method usage at Advanced configuration). To log certain attribute call the following method:

PAAnalytics.logAttribute(attribute_name, value: value)
PAAnalytics.logAttribute(attribute_name, value: value, type: .increment)

When you pass .increment as a type, server will increment by one the value with given name.

Keep in mind

Before logging a new event, make sure that the attribute name and expected value type are defined and approved in the dashboard Picsart Tools. Otherwise, the analytics backend will ignore this attribute.

Logging app attribution​

Use this function for logging app_attribution attribute with UTM parameters of the deeplink:

PAAnalytics.logAppAttribution(deeplinkURL:)

So for example, if the deeplink URL is 

https://www.picsart.com/?utm_campaign=spring_sale&utm_source=f&utm_medium=social_media&utm_term=photo_editing&utm_component=banner_ad

calling above function will result in logging app_attribution attribute with value of 

["utm_campaign": "spring_sale", "utm_medium": "social_media", "utm_source": "f", "utm_term": "photo_editing", "utm_component": "banner_ad"]

Register/unregistrer super parameters​

Register super parameter that will be automatically added to every subsequent event, regardless of its nature: custom event, standard event, or auto-event. Multiple parameters can be registered, and their order does not matter. Registered properties will be kept in memory and added to events until the app terminates or the specific super parameter is explicitly unregistered.

PAAnalytics.registerSuperParameter(forKey:, withValue:)

Unregister a specific super parameter. From this moment on, this super parameter will not be added to any subsequent events.

PAAnalytics.unregisterSuperParameter(forKey:)