Pugpig Bolt Analytics Starter Guide
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, some reports might be missing.
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 analytics specification can be viewed here, 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 email@example.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 firstname.lastname@example.org 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.
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.
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.
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.
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.
We have introduced BoltDownloadStarted, BoltDownloadCompleted and BoltDownloadFailed events (introduced in Bolt version 3.15) to track download behaviour. Downloads can be initiated by user activity, push or heuristically. Any download events that send with a pugpigTriggerMethod / KGLabel parameter value of 'Heuristic' have been initiated by background fetch activity.
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 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 metric is inflated by download events.
Currently the BoltDownload* events fire every time content is checked for updates regardless of whether a change has been made. We are making improvements to our BoltDownload* events in Bolt version 3.21 to ensure that the BoltDownload* events only fire if content has actually been updated. This should result in fewer BoltDownload* events being sent to your analytics provider.
Customers updating their iOS app to Bolt version 3.19 or later may also see 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. We're currently working on a fix to ensure screen views are only fired when a user foregrounds the app as a matter of urgency.
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
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.
We also recommend that you exclude heuristic BoltDownloadStarted, BoltDownloadCompleted and BoltDownloadFailed events from your foreground session activity.
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 here
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.
Why do I see (not set) values?
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, KGOrientation doesn't apply to BoltAudioFinishedPlaying but will still send as (not set). You can safely ignore these when viewing your reports.
What's the difference between GA4's Total Users and Active Users metric?
GA4's Total Users metric tracks 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. 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.
Why have our Subscriber Status and Notification Status values changed?
In Bolt version 3.16 we changed both our Pugpig Subscriber Status and Pugpig Notifications Allowed Status dimensions to user-scoped dimensions for all analytics providers that support doing so. Rather than sending with every analytics event, they now send per user. When a user's subscriber status or notification status changes, the user-scoped dimension updates to reflect the change. Users can consequently only sit within one category rather than multiple as was seen with the event-scoped dimensions (e.g. if a user signs up for an iTunes subscription, in that month they would be included in both the 'None' and 'iTunesSubscriber' categories). If you're not tracking the new user-scoped dimensions in your analytics provider after updating to Bolt version 3.16 or later please get in touch with Pugpig Support who will be happy to assist.
Why is our GA4 engagement duration so much higher on Android?
GA4's Android engagement time is known to be unreliable when automatic screen view tracking is disabled. 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. However we subsequently observed a spike in GA4's engagement time metric in our Android apps. Google are aware of the issue (see this Firebase issue) but it is yet to be fixed.
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. Therefore it is not compatible with our event-scoped custom dimensions. It is however supported in the Android SDK.
Can end users opt out of analytics? How many do?
Yes they can. The number varies enormously across our brands.
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
Nope. The apps don't sell retail products, so these reports don't make too much sense. We do track In App Purchases, however.
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.
Why do I see strange page names like RootViewController in my reports?
GA4’s preference for using Page Title and Screen Class as the default view in the pages and screens report. You should always apply the KGPageName dimension when looking at content.
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 http://docs.pugpig.com/en_US/analytics/4411734250385-GA4-Common-Reports-WIP-
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.