Events
This guide addresses using Events to track and understand user behavior

Overview

Events are intended to record various actions a user performs in the app. Unlike Tags that are used to store flat data (such as country, device model, or installation data), event data is stored historically and can be treated as a history of user behavior rather than a set of information about the device. All the contextual information about the event can be passed as a set of attributes and their values.
Once properly collected, this data can be used to:
  • trigger behavior-based messages;
  • build segments of users who perform a specific action in the app;
  • get insights about user flow, usage metrics, and other statistical data.

Implementation

1. Create events in Pushwoosh Control Panel

All events sent by your app must be created in Pushwoosh first with the set of attributes and their types; otherwise, Pushwoosh will not recognize them.
To create an event, go to the Events section of your Control Panel and press the Add event button. Enter the name and description and add the attributes if needed.
Event data is valuable only if it's submitted properly. Therefore, we strongly recommend following the simple guidelines below:
  • Try to name events as short as possible;
  • Name events after actions a user performs in the app - "LoggedIn", "SignedOut", "Subscribed", etc.;
  • Keep in mind that event names are case-sensitive;
  • Merge events that describe a single action into a single event. For example, use "Subscribed" event with proper attribution rather than separate "SubscribedToSports", "SubscribedToPolitics", "SubscribedToTechnology" events.

2. Set attributes

All details describing an event are provided with its attributes. Attributes are key/value pairs and can be of 5 different types: integer, string, list, date, and boolean. For example, you can track user logins and collect login credentials (e.g., logged in with Facebook, Google, Twitter, or email), internet connection type (wifi, cellular, unknown), and whether it was successful or not (true or false values) with a single Login event by specifying its attributes as follows:
attribute
type
value
type
string
facebook, google, twitter, email
connection
string
wifi, cellular, unknown
success
boolean
true, false
This event will be recorded in Pushwoosh with attribute values and a timestamp, so later it can be used for building segments, targeting messages, and collecting stats.

3. Call /postEvent API

When an event you’d like to track occurs in your app, call the /postEvent API to send this event to Pushwoosh.

iOS

Call the postEvent to send an event to Pushwoosh:
Swift
Objective-C
1
PWInAppManager.shared().postEvent("eventName", withAttributes: nil)
Copied!
1
[[PushNotificationManager pushManager] postEvent:@“eventName” withAttributes:@{}];
Copied!
To add details about the event (ref. to Attributes), use the attributes param as follows:
Swift
Objective-C
1
let attributes: [String : Any] = ["AttributedString" : "someString",
2
"AttributeInt" : 42,
3
"AttributeList" : [123, 456, "someString"],
4
"AttributeBool" : true,
5
"AttributeDate" : NSDate()]
6
7
PWInAppManager.shared().postEvent("eventName", withAttributes: attributes)
Copied!
1
NSDictionary *attributes = @{
2
@"AttributeString" : @"someString",
3
@"AttributeInt" : @(42),
4
@"AttributeList" : @[ @(123), @(456), @"someString" ],
5
@"AttributeBool" : @YES,
6
@"AttributeDate" : [NSDate date]
7
};
8
9
[[PushNotificationManager pushManager] postEvent:@“eventName” withAttributes:attributes];
Copied!

Android

When an event occurs in your Android app, use the following instructions to send this event to Pushwoosh.
Call the postEvent to send an event to Pushwoosh:
1
PushwooshInApp.getInstance().postEvent("eventName");
Copied!
To add details about the event (ref. to Attributes), use the attributes param as follows:
1
TagsBundle attributes = new TagsBundle.Builder()
2
.putInt("AttributeInt", 17)
3
.putString("AttributeString", "str")
4
.putDate("AttributeDate", new Date())
5
.putBoolean("AttributeBool", true)
6
.putList("AttributeList", Arrays.asList("item1", "item2", "item3"))
7
.build();
8
9
PushwooshInApp.getInstance().postEvent("eventName", attributes);
Copied!
You can also send events from In-App Javascript.

Purchase Events

Purchase Events are an analytical tool, helping you to measure your campaigns' success and ROI. Combining Purchase Events with Conversion Tracking, you can keep track of how much revenue your campaigns generate. To track Purchase Events, you need to pass two additional attributes with your event: __amount and __currency. The former passes the purchase cost and the latter specifies the currency name. Once you set up Purchase Events, Pushwoosh starts collecting info about your campaigns' revenue and showing this data in campaigns’ stats.

ISO-4217

Please note that currency must be listed in ISO-4217; otherwise, the revenue won't be counted in statistics.
Swift
Objective-C
Java
1
PWInAppManager.shared().postEvent("Buy", withAttributes: ["__amount" : 100,
2
"__currency" : "USD"])
Copied!
1
[[PWInAppManager sharedManager] postEvent:@"Buy" withAttributes:@{@"__amount" : @(100), @"__currency" : @"USD"}];
Copied!
1
PushwooshInApp.getInstance().postEvent(Buy, new TagsBundle.Builder()
2
.putInt(“__amount”, 100)
3
.putString(“__currency”, “USD”)
4
.build());
Copied!
There's no need to set up __amount and __currency attributes in your Control Panel. Instead, just check the Track Event Revenue checkbox, make sure your postEvent calls contain the amount and currency attributes, and Pushwoosh will monitor them automatically.

Default Events

Available starting from SDK 5.2.2
Default events are available out of the box for the up-to-date SDK versions and don’t need any additional settings (except for PW_InAppPurchase, see the instructions below). Just activate the event in your Pushwoosh Control Panel, make sure your SDK version is 5.2.2 or later, and every time a user triggers the event, its data is sent to Pushwoosh.

Application Open default event

PW_ApplicationOpen default event is triggered every time a user opens the mobile app. That comes in handy when you build user retention strategies, for example, messaging the users who have not opened the app for a long time.

Screen Open default event

PW_ScreenOpen default event keeps track of what screens of the app the users visit so that you can target those users with relevant messages based on what content users show interest in. The tech screen name gained from your app is tracked and stored.

App Minimized default event

PW_ApplicationMinimized is fired when a user minimizes the app on their device. Using this event’s data might be helpful to track the session time and adjust your app content and messaging campaigns. Please keep in mind the PW_ApplicationMinimized event only tracks app minimizing but not the force stops.
Site Opened default event
For web platforms only.
PW_SiteOpened tracks the first time a user opens a website.

In-App Purchase default event

For iOS only.
PW_InAppPurchase detects all the purchases of the in-app items specified in your apps’ App Store page, for example, paid subscriptions, game mechanics elements, etc.). To set the PW_InAppPurchase event, you have to set the Pushwoosh_PURCHASE_TRACKING_ENABLED param of the Pushwoosh SDK to 'yes'.
1
Pushwoosh_PURCHASE_TRACKING_ENABLED
2
// Allows the SDK to track in-app purchases. Needed for Customer Journey Builder.
3
// YES (default) / NO
4
// Type: Boolean
Copied!