انتقل إلى المحتوى

Collect reader data

هذا المحتوى غير متوفر بلغتك بعد.

Pushwoosh needs to know who your readers are and what they read, watch, or listen to. The User ID tells Pushwoosh who the reader is, events record the actions, and tags keep the current state of each reader, such as the topics they follow.

Identify readers by User ID

Anchor link to

Pushwoosh links all of a reader’s devices to one User ID, so your segments and journeys treat one person as one reader.

By default, Pushwoosh uses each device’s hardware ID (HWID) as its User ID. A reader who reads on a phone and watches on a tablet then counts as two readers, and an episode started on the phone can’t be matched with the same episode finished on the tablet.

To avoid this for readers who log in, set your own account ID as their User ID:

  1. Choose the ID to use. Take the account ID that your service already assigns to each registered reader or subscriber.
  2. Ask your developers to call setUserId with this ID when the reader logs in or signs up.
  3. Check the result. Log in to the app on a test device, then open Audience → User explorer, search by User Id, and enter the account ID. The reader’s profile opens.

Many readers of a news app never log in. They keep the HWID as their User ID, which Pushwoosh sets for them, and they still get pushes, enter journeys, and appear in segments on that device. What they read on another device counts for another reader.

To learn more about how User IDs relate to devices, see Users and User IDs.

Set up the events

Anchor link to

Events are how Pushwoosh learns what a reader does. Create them first, because segments group readers by the events they triggered, and journeys start when an event happens.

Plan both the events and their attributes before you build anything. Recommended events for media lists ready-made events with attributes, and Custom events explains how to define your own.

There are two kinds of events:

Default events

Anchor link to

The SDK sends these events for you. You need them to find readers who stopped opening the app before your custom events have enough history.

PW_DeviceRegistered fires when the app requests the token, not at install:

  • The SDK requests the token only when the app calls registerForPushNotifications. On iOS, this call also shows the permission prompt, and the token arrives whatever the reader answers.
  • If the app asks for permission later than the first launch, the event fires at that moment.
  • To catch new readers who create an account, use the Signed up custom event instead. See Choose the events to track.

An event appears in Audience → Events after the SDK sends it for the first time. For details on these and other default events, see Default events.

Custom events

Anchor link to

Custom events record what happens in your app, such as reading an article or starting an episode. You choose which ones the app needs, your developers send them, and you check that they arrive.

Choose the events to track

Anchor link to

Choose the events your app needs and the attributes each one carries. The tables list examples: use them as they are, rename them, or add your own. A news app needs the reading events, a streaming app the episode events. Track only the events that the journeys you launch need.

Events for the minimum setup
Anchor link to

This event is enough to launch the minimum setup.

EventWhen it firesKey attributesWhat it drives
Content readReader opens an article, a video, or a podcast episodearticle_id (string), category (string)Active readers and At-risk readers segments, conversion goal of Win-back for inactive readers
Events for other journeys
Anchor link to

You can add these events together with the first one or later, when you build the journeys that use them. If readers subscribe through the App Store or Google Play, Pushwoosh records the store events for you. See Track subscriptions from the stores.

EventWhen it firesKey attributesWhat it drives
Content preferencesReader follows a topic, a show, or an authortopic (string)Conversion goal of Welcome and topic choice, push permission flow
Signed upReader creates an accountsignup_source (string)Welcome and topic choice journey
Episode startedReader starts an episode of a series or a podcastseries_id (string), series_name (string), episode_id (string)Continue watching journey
Episode completedReader finishes the episodeseries_id (string), episode_id (string)Continue watching journey
Paywall viewedReader opens content that needs a subscription and sees the paywallarticle_id (string)Paywall hitters segment, Paywall follow-up journey
Subscription startedReader buys a subscription on your website or in your own billingplan (string), __amount (decimal (price)), __currency (string)Conversion goal of Paywall follow-up, revenue
Subscription canceledReader cancels a subscription bought on your website or in your own billingplan (string)Cancelled subscription journey for website subscribers

Send the events from the app and your server

Anchor link to

Agree with your developers which events the app sends and which attributes each one carries. The names of the events and attributes must match exactly.

The app sends each event with postEvent. Your server sends Subscription started, because the app does not know about a subscription bought on your website. It uses the same postEvent method of the API.

To check that an event arrived, open Audience → User explorer, find a test reader, and open the Events history tab.

Code examples for your developers
Anchor link to

These examples show what your developers send for the events above.

The app sends Episode started with its attributes like this:

TagsBundle attributes = new TagsBundle.Builder()
.putString("series_id", "S-204")
.putString("series_name", "The Long Road")
.putString("episode_id", "S-204-E03")
.build();
InAppManager.getInstance().postEvent("Episode started", attributes);

The server sends Subscription started with the reader’s userId instead of a device, and a Device API token in the Authorization: Token <token> header:

POST https://api.pushwoosh.com/json/1.3/postEvent
{
"request": {
"application": "XXXXX-XXXXX",
"userId": "reader-20931",
"event": "Subscription started",
"attributes": {
"plan": "monthly",
"__amount": 9.99,
"__currency": "EUR"
}
}
}

Track revenue from subscriptions

Anchor link to

Pushwoosh counts revenue from PW_Conversion, which records the amount and currency of every purchase in one format. You need it to compare revenue in Conversion events.

You do not need a separate call. Send Subscription started with these attributes:

  • __amount: the price of the subscription, as a number.
  • __currency: the currency, as an ISO 4217 code, such as EUR. Pushwoosh drops a currency that is not a valid code.

The first time the event arrives with both attributes, Pushwoosh turns on revenue tracking for it, unless you already set up revenue for this event in Conversion events. From then on, each Subscription started with these attributes also records a PW_Conversion event with the same amount and currency. See Automatic revenue mapping.

Track subscriptions from the stores

Anchor link to

If readers subscribe in the app through the App Store or Google Play, Pushwoosh receives the status changes of their subscriptions from the stores. Each change arrives as a PW_Subscription* event with the productID and expiresAt attributes, for example:

  • PW_SubscriptionStart: a reader subscribes.
  • PW_SubscriptionCancel: a reader turns off auto-renewal. The subscription stays active until the paid period ends.
  • PW_SubscriptionResume: a reader turns auto-renewal back on, or subscribes again in the App Store. A new purchase in Google Play arrives as PW_SubscriptionStart.
  • PW_SubscriptionExpired: the subscription has ended.

The store events don’t show a free trial: a trial that starts arrives as an ordinary PW_SubscriptionStart, and nothing marks its end or conversion. To remind readers before a trial ends, send your own event from your server, for example Free trial started with the trial end date in expiry_date. For more subscription events, such as renewals, see Recommended events for subscription management.

Use these events to start journeys, for example an offer to a reader who turned off auto-renewal. See Cancelled subscription.

The store events carry no amount, so they do not record revenue. Subscriptions bought on your website don’t reach the stores, so send them as Subscription started from your server, and their cancellations as Subscription canceled.

Store reader data in tags

Anchor link to

A tag is a value that Pushwoosh stores on a reader’s profile, such as the topics the reader follows or whether the reader is a subscriber. An event records what happened, and a tag keeps the current state. Tags help you to:

  • Send a message only to readers with a certain value, for example a news alert only to readers who follow politics.
  • Leave readers out of a message, for example subscribers out of a subscription offer.

Tags are optional. The journeys in this playbook run on events and on default tags that Pushwoosh sets itself, so you can start without your own tags. Add them to send news alerts by topic or to tell subscribers apart. See Segments by tags.

Your own tags

Anchor link to

Your developers send tag values from the app or your server, or you can import them from a CSV file. Pushwoosh handles a new tag like this:

  • On most accounts, Pushwoosh creates the tag the first time your developers send it, as a User-specific tag.
  • If a tag doesn’t appear in the Control Panel after the app sends it, create it there.
  • To choose the type of a tag yourself, create the tag in the Control Panel first. See Tags.

These tags are examples. Rename them to match your service, and add your own:

TagTypeExampleWhat it drives
followed_topicsListpolitics, footballNews alerts to the readers who follow a topic
is_subscriberBooleantrueLeave subscribers out of subscription offers, or send them their own content

A List tag keeps several values for one reader: a reader who follows two topics is in the segment of each topic.

Ask your developers to:

  • Update followed_topics every time the reader follows or unfollows a topic.
  • Set is_subscriber when a subscription starts or ends.

When you create a tag in the Control Panel, keep User-specific turned on, as it is by default. Pushwoosh then keeps one value per User ID, so the value belongs to the reader and not to one of their devices. See Identify readers by User ID.

When a reader logs in, the events and User-specific tags that the device recorded before stay with the HWID. Device-specific tags, which have User-specific turned off, move with the device to the new User ID.

Default tags

Anchor link to

Pushwoosh stores these default tags for every device, so you do not create them:

  • Language: the language of the device. Pushwoosh uses it to send each reader the message in their own language.
  • Last Application Open: when the app was last opened on the device. Use it to find readers who stopped opening the app.
  • Push Alerts Enabled: whether notifications are allowed in the device settings. Use it to show an in-app message only to readers who have not allowed them yet.
  • Country: the country of the device. Use it to send a local news alert only to readers in one region.