How to Track In-App Events

 

By tracking the right in-app events in your app, you can measure the success of your organization's marketing efforts through the KPIs that are important to you.

This guide applies to new Growth Plan customers. For other customers, the process is slightly different as events are not added automatically to the Events page (see step 5 below). This feature is being rolled out to all customers.

Guide for Marketing and User Acquisition Teams
Prerequisites

Use Singular as your attribution partner (MMP).

To track events, you need to:

  1. Choose events that you want to track.
  2. Ask your developers to include code in the Singular SDK or S2S integration in your app to send your chosen events as they occur.
  3. Make sure your events appear on the Settings > Events page in the Singular platform.

events1.jpg

Follow the guide below for detailed instructions.

1

Define a list of events

Think of the KPIs you want to measure, and list the in-app events that will help you measure them.

To help you get started, we have compiled a list of commonly used events per vertical, including the recommended attributes to pass. We recommend using these standard events whenever possible, as they are automatically imported in Singular.

For example, for e-commerce apps, we recommend implementing events such as Product View, Add To Cart, and Checkout.

(Optional) Add Custom Events if Needed

Depending on your app's content and your marketing needs, you may want to track in-app events that do not easily map to any of the Singular standard events. In that case, you can define your own custom events.

Custom events must be manually configured in Singular to be measured in Singular reporting. Depending on the ad network, you may or may not be able to use them for optimization.

Note: Even if you define custom events, we still recommend using standard attributes wherever possible to pass data with the event. This will help ad networks report on your attributes. Standard attributes will also be reported by Singular in the near future.

2

Implement events in the SDK integration

Give your development team the list of events and attributes to incorporate into the Singular SDK integration.

The goal is for your app to report every chosen event as it happens to the Singular servers, so that:

  1. Singular can aggregate and analyze the information for you.
  2. Singular sends automatic postbacks to ad networks about events in your app. See Postbacks FAQ.
Which events are built-in and always implemented?

When you integrate a Singular SDK or S2S into your app, Singular tracks several types of in-app events automatically, without you having to add code to send them to Singular when they happen.

These built-in events may appear in:

Supported Built-In Events

Event Name Description When It Is Tracked
__START__ Install Automatically tracked when the first session is sent through an SDK/S2S integration.  
__SESSION__ Session Automatically tracked when sessions are sent through an SDK/S2S integration.
__iap__ SDK Revenue Tracked if an SDK/S2S integration is reporting a revenue event through the revenue method.
__REVENUE__ Any Revenue

Tracked if any revenue is reported, for example:

  • If an __iap__ event is triggered
  • If the SDK reports an ad revenue event
  • If you are reporting revenue via S2S with an event name like "purchase".
  • If you are reporting other revenue events such as "refund" or "offline purchase"

Note: We do not recommend sending postbacks for this event if you are already sending postbacks for __iap__ or other revenue events, as you may end up reporting duplicate revenue.

__UNINSTALL__ Uninstall Automatically tracked if uninstall is enabled for your iOS or Android app, and at least one uninstall has been tracked. If an uninstall is detected for a device, it is triggered once a day.
__REINSTALL__ Reinstall Automatically tracked if uninstall is enabled via the SDK/S2S. If an __UNINSTALL__ for a device is tracked, and then a subsequent __SESSION__ is triggered, the __REINSTALL__ event is also triggered

Use the events implementation guide for the appropriate SDK/S2S. The guide describes how to implement both standard and custom events (if you use them).

Event Implementation Guides per SDK:

iOS SDK Integration Singular S2S Integration: Tracking Events
Android SDK: Tracking Events & Revenue Flutter Integration
Unity SDK: Tracking Events & Revenue mParticle Integration
React Native SDK: Tracking Events & Revenue Segment SDK Integration
Unreal Engine SDK: Tracking Events & Revenue Segment S2S Integration

Note: the standard event/attribute names may vary a little per platform, e.g., sngLogin instead of sng_login, depending on the platform's guidelines for entity names. Each SDK's guide links to an up-to-date list of standard events available in the specific platform and their names as they need to appear in the code.

3

Check your events in the Singular Platform

Define events on the Settings > Events page to see them in your aggregated reports.

Once your app starts sending standard events to Singular, they are automatically added to the Events page. For each event in the SDK, Singular creates a unique event and a non-unique event in the UI. See Understand the Event UI below.

Note: If you remove an event, Singular won't re-add it automatically, but you can always re-add it manually.

 

Understand the Cohort Event UI

The Cohort events tab shows you a collapsed list of events that were added automatically. When you expand an event, you see its properties.

events3.png

  1. Name and collapse icon: the name you provide here will be shown in the reports UI.
  2. Unique Event filter: This toggle changes whether unique or non-unique events from your MMPs are available to aggregate. See Understand Event Measurement - Unique.
  3. Data sources: Select the events from Singular or your ad networks to aggregate into this event. You can aggregate multiple events into one. After an event is saved, it is locked.
  4. Add calculated metrics: See FAQs for CPE and ECVR.
  5. Delete event: Remove your event. The events page is limited to 12 events*.
  6. Save changes and Cancel changes buttons
  7. Event History

*Note: Because of the 12-event limit, Singular automatically adds up to 6 unique and 6 non-unique versions of your SDK events. Enterprise customers are not limited to 12 events.

Once a cohort event is saved, any SDK events added cannot be edited. Notice the lock icon next to events. You can still add more SDK events to aggregate into the same cohort event.

Understand the Conversion Event UI

The Conversion Events tab shows you a collapsed list of events from your ad partners. When you expand an event, you see its properties.

events4.png

  1. Name and collapse icon: the name you provide here will be shown in the reports UI.
  2. Data sources: Select the events from your ad networks to aggregate into this event. You can aggregate multiple events into one. These events can be edited freely.*
  3. Add calculated metrics: See FAQs for CPE and ECVR.
  4. Delete event: Remove your event. The conversion events page can have unlimited events.*
  5. Save changes and Cancel changes buttons
  6. Event History

*Note: Unlike cohort events, configured conversion events are not limited and you can edit the events freely. Notice the "x" icon next to each event.

Adding Custom Events Manually

If your SDK sends custom events to Singular, they are not added automatically to the Events page. You have to add them manually by clicking New Event and defining the event details.