Introduction

Pugpig comes with a tried and tested integration with Google Analytics, which is collected from the apps using the Firebase SDK, and from the website using standard GA tags.

Note: This document is entirely related to using Google Analytics and the Firebase SDK. To see a list of other providers we have integrated with, please look here. If you are using a different provider, we can help you understand what information we are sending, but we trust your expert analytics teams to be able to test the integration and run the reporting. If you are on GA 360, this document may be missing some of the additional functionality you have access to.

The latest versions of our products (Pugpig Bolt) have an improved analytics structure. If you’ve recently upgraded your Publish app, you’ll notice some improvements but will need to adapt existing reports.

Our Pugpig Analytics Specification contains a full list of every event, screen and custom dimension that we track. It’s been honed over many years of working with publishers and tracks almost anything our product can conceivably do. Our tracking also grows over time as features are added or improved, and based on feedback from our customers.

We’re always happy to field questions about our spec and improve our tracking where necessary. If there are things you and your analytics teams are trying to track but aren’t sure how, get in touch with support@pugpig.com. 

Over the last couple of years, Google have migrated the core reporting tools from the Universal Analytics platform to the new Google Analytics 4 platform, which is tightly-coupled to Firebase. There are notable changes between the two, and GA4 is regularly evolving. We recommend following Google’s documentation on understanding the changes.

Apart from the standard Google Analytics, other useful places to find and cross reference information are:

• The reporting from the App Stores (iTunes, Google Play and Amazon). These are always the most accurate source of information regarding revenue.
• Push notification reporting from the push provider (Firebase and Airship are the supported ones). We can send custom data for segmentation to these providers.
• Bandwidth usage (available from the Pugpig Distribution Service)
• Crash Reporting from Crashlytics, which is available in the firebase dashboard

Getting it set up

Here’s our guide on setting up GA4, as well as a brief explainer of the differences between it and previous versions of Google Analytics.

We generally request that we're added to your analytics properties as an admin so that we can configure your custom dimensions and help troubleshoot where necessary. We use the address analytics@kaldorgroup.com for this access, rather than specific team members.

How to test your analytics

Often it’s helpful to send some events of your own and see them in the dashboard. GA4 (and UA) offers a real time view and you should be able to isolate your device with a combination of filters (device model and location often work wonders). That way you should be able to see just your events and understand how they would track.

Basic Concepts

Screens

The apps track a number of distinct screens, as detailed in the spec. Note GA4’s preference for using Page Title and Screen Class as the default view in the pages and screens report. This doesn’t suit our content model, but changing to Page Title and Screen Name at the top of the table will get you what you want. You should always apply the KGPageName dimension when looking at content.

Custom Dimensions

Google Analytics allows you to attach custom dimensions to every event. The out of the box reporting includes many of these. For the full list and their description, see here.

We also have the ability to send two different kinds of custom dimension specifically for you. Content-based custom dimensions, which are related to the article being viewed, for example your internal unique ID for an article. User based custom dimensions are related to the logged in user. Examples would be Subscription Tier, User ID or Company of the user.

Custom analytics

If our out-of-the-box analytics tracking doesn't cover every user or event attribute you would like to monitor in your analytics provider, you can send addition custom analytics dimensions / properties too.

To send content-related custom dimensions, for example publish date or article tags, you'll need to ensure that the all dimensions you wish to track are included in your RSS feeds.

If you would like to send customer user attributes, for example more granular subscription information or a user ID, you need to include the information in your auth response. Our DUTA model details how data should be sent in the auth response.

Note: there are a number of property names that are reserved by Firebase / GA4 that cannot be used for custom dimensions. This list can be found in this Google doc.

Custom dimensions and (not set) values

It is common to see a value of (not set) against custom dimensions in GA. This is an issue with firebase itself, whereby all dimensions are recorded for all events. However, certain dimensions don't/can't apply to these events. For example, KGVideoTotalSeconds doesn't apply to BoltAudioTrackComplete but will still send as (not set). We are also unable to send our own custom dimensions with a number of Google's automatically tracked events including session_start, user_engagement etc. You can safely ignore these when viewing your reports.

URL Structure/Deep Links

Our URLs follow a defined structure you can read about here. These often map to our deeplinks, which allow users to go to specific destinations or trigger certain functionality you can read more about deeplinking here.

Tracking purchases and revenue

We always recommend you get any business-critical information about revenue and subscriptions directly from the stores themselves. However, GA4 does offer some level of revenue reporting if the connections are configured correctly. This configuration is done in Firebase, and allows Firebase/GA4 to communicate directly with the stores.

The list of relevant events tracked by GA4 can be found here: https://support.google.com/analytics/answer/9234069 any events beginning with app_store as well as the in_app_purchase event pertain to the revenue tracking.

Note that we do not track anything to GA's ecommerce reporting, as this pertains to actual shopping and checkouts within apps, which don't form part of our product.

Note that free trials will report a revenue value of 0, hence many purchase events showing 0 revenue. The revenue of converted trials will be tracked to the app_store_subscription_convert event.

Bolt subscription events

We do offer our own BoltSubscription* events to help you track engagement with the subscription flow including when a user clicks on the subscription button (BoltSubscriptionClicked), when they select a subscription offer (BoltSubscriptionChosen) and when they successfully purchase a subscription (BoltSubscriptionPurchase). Again, we recommend using the app stores as your source of truth on purchase numbers.

Please note: on iOS the BoltSubscriptionPurchase event tracks both the initial purchase and subsequent renewals. On Android the BoltSubscriptionPurchase event only tracks the initial purchase.

Users

GA has two ways of measuring users: Total Users and Active Users.

Total Users includes all unique users who have recorded any event within the time period in question. This metric includes users who have registered activity whether the app is in the foreground or the background. As a result, it includes activity that occurs without user interaction such as when background fetch occurs or when a user tracks a ‘notification_received’ event. Total Users was the primary metric in Universal Analytics.

The Active Users metric counts the number of unique users who have had an engaged session (a session that lasted 10 seconds or more, or featured a conversion event or 2 or more screen views) or when the first_open event or engagement_time_msec parameter (Android) or user_engagement event (iOS) is tracked.

Active Users is the primary metric in GA4 meaning wherever you see 'Users' in any of GA4's standard reports, it's referring to Active Users. For this reason, we recommend you default to using Active Users in your own explorations and reporting. For more information about users in GA4, check out Google's Documentation.

Subscriber Status

Use the pupigSubscriberStatus / KGSubscriberStatus dimension to determine the types of users accessing your apps. Below is a list of definitions for the different subscriber states that users can belong to:

Background fetch and analytics

In order to enhance the availability of content, Bolt uses background fetch to wake up the app while it is in the background of a user's device to retrieve new content from the server. It has been turned on by default for all apps since Bolt version 3.19 on iOS and Bolt version 3.3 on Android. More information about Bolt download behaviour, is available in our Bolt Download and Offline Behaviour documentation.

If you have recently switched on background fetch or updated to the latest version of Bolt it may impact your analytics.

Download events

Bolt version 3.15 introduced enhanced tracking for download behaviour in the form of three events:  BoltDownloadStarted, BoltDownloadCompleted and BoltDownloadFailed. Downloads can be initiated by user activity, push or heuristically (by the background downloader). The type of download is indicated by the pugpigTriggerMethod / KGLabel parameter.

Subject to the way that users are tracked in your analytics provider, background fetch activity and the resulting BoltDownload* events may contribute to a spike in your user and session numbers. This is because they attribute events to individuals who have the app downloaded on their device but who may not have opened the app. We know, for example, that GA4's Total Users and Sessions metric is inflated by download events.

Screen views

Customers with a iOS Bolt app on version 3.19 or 3.20 may have seen an increase in their screen view events due to the fact that it is standard practice with iOS background fetch to render the app screen in the background so that when the user launches the app, the new content is readily available. Bolt versions 3.21 and later suppress the background screen view event, ensuring that screen view events are only fired when a user foregrounds the app.

We're also aware of another case where Apple will background launch the app in order to "prewarm" it (for devices on iOS 15 and later).

Filtering out background activity

Users

For customers who use GA4, the Total Users metric tracks any user who has logged any event within the specified time period regardless of whether they open your app. The Active Users metric on the other hand only includes users who have an engaged session. Active Users is the primary metric used by GA4 itself and it is for this reason that we recommend you use it as your default user metric too.

Sessions

GA4 fires an automatically collected 'session_start' event when it detects that a session has begun. Unfortunately it does so in response to detecting our BoltDownload* events meaning that they're artificially inflating session volumes in GA4.

In order to ensure that your session data is valid, we recommend that you filter your report to only include sessions that contain a screen_view event. You can do so by creating a session segment or by adding a filter to your exploration where event name = screen_view.

Creating a session segment that includes sessions only when they contain one or more screen views

If your analytics provider allows, we also recommend that you exclude BoltDownloadStarted, BoltDownloadCompleted and BoltDownloadFailed events with a KGLabel / pugpigTriggerMethod value of 'Heuristic' from your foreground sessions.

FAQs

General

Can end users opt out of analytics? How many do?

Yes they can. The number varies enormously across our brands.

Do analytics work for users that are offline?

Sure! The SDK collects the data while offline and forwards it to the servers when a connection is restored.

How does this relate to Google Play's Data Safety requirements:

You can find all the information about that in our Completing the Google Data Safety form for your Pugpig app documentation.

Why don’t my analytics line up exactly with the reporting from the App Stores?

Users opting out. Different periods. Different lag times. For these reasons we always suggest using the store data for revenue reporting, as it is the final source of truth.

Why don’t my analytics line up exactly with the reporting from my Push Provider?

Different SDKs cannot be guaranteed to handle the same data the same way, and thus small variances are to be expected, but if these differences are substantial we can investigate

Do you support eCommerce Reporting?

No. The apps don't sell retail products, so these reports don't make too much sense. We do track In App Purchases, however.

How do I track downloads of my app?

To see true download numbers it's best to get them directly from App Store Connect or Google Play Console. However you can get a proxy for them in your analytics provider using:

• Firebase's first_open event
• New users in your analytics provider

Does listening to audio count towards session duration?

Only if the app is in the foreground while the user is listening. If the user continues to listen after navigating away from the app, the time that the user spends listening will not count towards session duration.

Why do I see strange page numbers instead of page names?

If your app includes a copy of the print version the page name will be a page number. 

For more information on how to find commonly-used metrics and reports in GA4 see our GA4 commonly-used metrics and reports documentation

Why do the different KGSubscriberStatus values not add up to total users?

Users are able to move between states. For example, a user may download the app for the first time at which point their KGSubscriberStatus value is None. Then log in at which point their KGSubscriberStatus value changes to ExistingSubscriber.
 

Google Analytics

Why has our GA4 engagement duration dropped on Android?

In May 2024, Google rolled out a fix for their engagement duration tracking issue which elevated engagement duration on Android when manually tracking screen view events. We disabled automatic screen view tracking on Android in Bolt version 3.14 to allow us to send our own custom dimensions (such as page type and page name) with screen view events. As a result, you may see elevated engagement duration volumes on Android from the time your app updated to Bolt version 3.14 (or later) until the fix was released in May 2024. For more information, please see this Firebase issue.

Why can I not track engagement duration against any custom dimensions for iOS users?

Firebase currently does not support sending the user engagement duration parameter against our iOS screen_view event (see Firebase documentation). Therefore it is not compatible with our event-scoped custom dimensions. It is however supported in the Android SDK.

Why do I see strange page names like RootViewController in my reports?

GA4 uses Page Title and Screen Class as the default view in the pages and screens report. You should always apply the Page Title and Screen Name dimension when looking at content. When looking specifically at articles, you can use KGPageName.
 

Analytics integrations

What analytics platforms do you have integrations with?

You can find a list of all of the analytics platforms that we support in our available third-party integrations document.

What is the difference between the Firebase SDK and the Google Analytics SDK?

Good question! Google do not make this very clear. The Firebase SDK tracks to Firebase and then events are automatically sent into GA. The GA SDK is no longer under active development. Google no longer recommend or support the Google Analytics SDK in apps, even for Google 360 customers: https://support.google.com/firebase/answer/9167112?hl=en

Universal Analytics is being fully deprecated on the 1st July 2023, after which all reporting will utilise GA4. If you aren't sure if your apps or sites are tracking to GA4, get in touch.

Can I see my In App Purchase Reports without GA4 (e.g. Universal Analytics or GA 360)?

Sadly not. Google have told us we should be optimising everything for GA4. You can get this information from Firebase, or directly from the App Stores.

Can I rename events/parameters to what I like?

GA4 allows you to modify event parameters upon receiving them (i.e not at the source). This is detailed in their documentation. If you'd like greater control such as blocking events from being recorded entirely, or transforming the event names as well as their parameters then the Google Tag Manager SDK is available for this purpose, this requires additional set up and an app submission to enable, after which you'll be able to make any transformations using the Google Tag Manager dashboard.