App Push Notification Engine Guide



App Push Notification Engine Guide

cmercury Engagement Platform – User Manual

Deliver the right message to the right user at the right time even, so you can retain and engage your audience and drive real business results from your mobile app.

01

All cmercury features are designed to help you retain and engage the audience of your app. After all, it is how today’s customers, guests, fans and loyalty card members want to interact with your brand or business. Whether your app is intended to improve the guest experience for holidaymakers who visit your resorts, engage sports fans on match-day, both inside and outside of the venue or to increase footfall to your franchises and improve the in-store ordering experience, effective engagement involves delivering the right message to the right user at the right time.

The cmercury feature set is tailor made for busy app developers and mobile marketers to do just that.

Push Notifications & In-App Messaging

Push Notifications are an effective way to keep users engaged with an app. With cmercury, you can schedule marketing campaigns from the console or send push notifications automatically in response to events by using Automations, for example, when a user enters a Geofence, or via the Push API.

In-app messaging allows you to deliver rich, personalized content to users whilst they are in the app. Use in-app messaging to boost conversion through the on-boarding journey, highlight special offers, ask users to rate your app, subscribe to receive push notifications and much more.

xxx

Push notifications and in-app messaging can be combined and used together for maximum effect. Once enabled and configured, you will be able to send unlimited push notifications and in-app messages to users of your app on both iOS and Android devices. You can use segments, channels, geofences and beacons to target your audience, trigger automations and schedule campaigns.

Audience & Engagement Analytics

Analytics collates all of the data from Messaging and Diagnostics together with the usage of the app itself to give vital insights into the audience (who is using the app, where and on what devices), user retention (who is still active after 7 or 30 days), engagement (when is the app used and for how long) and conversion (through key user journeys). All of this helps you make informed decisions on how to refine your messaging strategy and campaigns to increase retention, engagement and conversion.

Analytics events can be used to trigger automations such as run a script or send a push notification.

Reporting lets you generate weekly and monthly reports summarizing who is using your app, how engaged they are with your app and how well the app is performing. You can run as many reports as needed, annotating and customizing the content if required prior to delivery to your client.

The RESTful Analytics API lets you access the underlying data should you wish to present elsewhere. If you want to export analytics events into any other data warehouse or BI tools such as Big Query then you can do this with our powerful, serverless scripting engine, KScript.

Crash Reporting & Diagnostics

You work hard to acquire users for your app, but they will have no hesitation uninstalling your app if it crashes, has bugs or is slow. Crash Reporting & Diagnostics gives you complete visibility into the user experience and technical performance of both your app and all the services it depends on to function so you can pro-actively minimize the impact of any problems on your audience.

Monitoring Checks alert you when there are problems with any of the API Endpoints that your app depends on to function, such as an endpoint being unreachable, returning the wrong response code, having a slow response time or returning a data payload with the incorrect shape.

Crash Reporting alerts you when exceptions occur in your app, providing all of the information needed to pro-actively prioritize and fix issues before they negatively impact retention rates.

App Store Optimization (ASO)

App Store Optimization lets you see how well your app is performing in the App Store and Play Store, including recent reviews and how your app ranks for certain keyword searches vs. competitive apps.

Backend & Serverless Scripting

Backend is our mobile Backend-as-a-Service (BaaS) feature that allows you to use the cmercury Mobile Engagement Platform to manage the content in your app via easy-to-use, SQL based data storage in the cloud and RPC API Methods to access and manipulate data from one of our many mobile SDKs (including Objective-C, Swift, Android, Cordova & Ionic, Xamarin, React Native, Unity and more) or server-side, via REST, PHP or any HTTP Client.

KScript is our powerful, serverless scripting engine. KScripts can be called directly from the mobile SDK, invoked in automation rules triggered by analytics events or run on a schedule, for example to interrogate raw analytics event data and export into data warehouse or BI tools such as Big Query.

Getting Started » Integrate into your App

This guide will walk you through everything you need to do and they key considerations to integrate cmercury into your app. This should only take you a few hours per platform.

Add the SDK

cmercury has a number of mobile SDKs. All of our SDKs are hosted on GitHub and can be added to your project using the appropriate package manager for that language. For example: Carthage or CocoaPods for Objective-C and Swift, JCenter for Android and NPM for React Native. To add the SDK to your project, please see the appropriate README on GitHub:

  • Swift
  • Objective-C
  • Android JAVA and Kotlin
  • Cordova & Ionic
  • Xamarin
  • React Native
  • Unity

Initialize SDK

To initialize the SDK, you will need your app’s API Key and Secret Key. Click on the app in your console and you will see this at the bottom of the dashboard.

Use these credentials to initialize the SDK early in your application startup as shown in the integration guide for each SDK. For example: for Swift…

When you now run your app on a simulator or install your app on a device, Anayltics data will be sent to cmercury. To check that the SDK has been initialized correctly, click on the Installs tab. This shows the ten most recent installs of your app (platform, device model and installation id).

Click on any install to see more information. The Overview tab shows more details about the installation including app version, when the app was installed, the approximate location (to help identify test devices and installs) and the locale being used.

Enable Crash Reporting

Crash Reporting allows you to track unhandled exceptions in your app, and optionally log any caught exceptions for further investigation. Crash reporting is not enabled by default. Click the Start button next to Diagnostics on the App Dashboard.

Click Get Started and now, simply modify your cmercury initialization to include enabling crash reporting as shown in the integration guide for each SDK. For example: for Swift…

Unhandled exceptions that lead to crashes will now be recorded automatically and shown in your App Delivery Console.

If your app relies on any other APIs or services to function, add API Endpoint Monitoring checks to test are all the API Endpoints reachable? Returning the correct response code? Returning data to your app in the expected format? And how long do they take to do this? Monitoring checks will alert you to any problems before they impact your audience.

Enable Push & Messaging

cmercury provides powerful, omni-channel messaging to retain and engage the audience of your app. Click the Start button next to ‘Messaging’ on the App Dashboard.

Enable In-App Messaging

Modify your cmercury initialization to include enable in-app messaging as shown in the integration guide for each SDK. For example: for Swift…

Next, enable the ‘background-fetch’ Background Mode in your Xcode project’s Capabilities section.

This will auto-enroll all users to receive in-app messages. If you want to let your users opt-in to receive in-app messages, you can change the consent strategy during SDK initialization to make opt-in explicit and then call the SDK helper to manage consent as shown in the integration guide for each SDK.

Configure Push Gateways
In order to send push notifications to iOS and/or Android devices you must configure the Apple Push Notification Service (APNS) and/or Firebase Cloud Messaging (FCM) and upload your push certificate to cmercury.

APNS Configuration
In order to send push notifications to iOS devices with cmercury, you’ll need to create certificates in the Apple Developer Member Center. The steps to complete this are shown in the video guide.

Video Guide

FCM Configuration
In order to enable push notifications for Android with cmercury, you’ll need to set up an FCM project and configure push for your app. These steps are shown in the following video guide.

Video Guide

Upload to cmercury
Now, in cmercury, open ‘Messaging’ in the left-hand menu, click CONFIGURE NOW and then click the cog icon next to the platform you would like to configure to open the dialog where you can enter the required information to send notifications to iOS devices via APNS and/or Android devices via FCM.

Register for Push Notifications
When you consider it appropriate, you need to request permission from the user to send them push notifications. Alternatively, you can use a cmercury in-app message to prompt the user to accept push notifications at a later time.
Whilst you can handle this yourself, cmercury provides a convenience method:

Kumulos.pushRequestDeviceToken()

This will prompt the user to accept push notifications. When the user accepts, the cmercury SDK will store the push token.
When adding cmercury to an existing app, we suggest

calling pushRequestDeviceToken as soon as the app is opened for the first time after update.

Supporting Pictures In Push Notifications on iOS
When sending a push notification, you can attach a picture to it, which will show on Android 4.1+ and iOS 10+ devices (where it will expand upon swiping the notification on devices supporting 3D Touch). There are no additional steps required to enable this functionality for Android. However, in order to enable this functionality for iOS you need to add a Notification Service Extension to your application.
If using CocoaPods, add the following to your Podfile and run pod install instead of manually linking the SDK framework:

Then replace the contents of NotificationService.swift with the following lines:

The cmercury helper function adds picture attachment to the notification content. You can modify the content before calling didReceive or replace the implementation with you own.

Please see the integration guide for each SDK for further details on customizing push launch behaviour, opening URLs, handling background data and managing the app inbox.

Send Location Updates

If you want to use the geotargeting features of cmercury, then your app needs to send location updates to cmercury.
How frequently you send location updates to cmercury will depend on the specific use case of your app. You should consider both accuracy and battery life when making this decision. For most cases, using the Significant-Change service on iOS and the Fused Location Provider on Android will be sufficient.

For details of how to send location updates to cmercury, see the integration guide for each SDK. As an example, in Swift, once you have created a CLLocationManagerDelegate you can use the helper method in the cmercury SDK to send location updates to cmercury.

Associate Users

If your app has user-based authentication, then cmercury allows associating an anonymized user identifier with the current installation ID (for example for targeting via Push API. You can optionally associate a collection of attributes with the user, which can be used to create audience segments. Each cmercury SDK provides a helper method to associate users. For example: in Swift…

When adding cmercury to an existing app, we suggest calling associateUserWithInstall when a new user signs up, an existing user logs in AND when the app is opened for the first time after update (for users who are already logged in to the app). As this method is idempotent, it may be simpler to just call this method every time the app is opened.

Track Analytics Events

Analytics events can be used as triggers to fire automation rules (e.g. to trigger a notification), as steps in a funnel to track conversion through key user journeys in your app or simply to answer questions on how the app is being used. For example: What is the most viewed screen? Which product category is most popular? How does this vary between customers and non-customers? Etc.

Each cmercury SDK provides a helper method to track analytics events. For example: in Swift to track an event when someone purchase a product, including the product identifier as a property, use Kumulos.trackEvent as follows:

Event tracking is available offline as all events are persisted locally before being synced to the server in batches in the background.

A similar method trackEventImmediately will immediately start an event sync rather than waiting for the next time the app is backgrounded.
What analytics events you should track, will depend on the use case of the app. However, we would recommend tracking all steps through the first launch / onboarding flow including, any signup and user registration events. We would also recommend tracking any purchase or subscription events and an event for each screen in the app (so you can see how the app is being used).

Submit to Stores

You are now ready to submit your app or update to the stores for approval. Ensure you have added all of the features you are using to your cmercury subscription first to avoid your app being rejected.
Once the app has been live, use App Store Optimization to:

  • Track where your app ranks in search results versus competitive apps
  • View volume, contention and ranking over time for different search terms
  • Compare your App Store listing and Google Play Store listing side-by-side
  • Compare your listing to that of competitive apps and top apps in category
  • View the most recent and also most helpful reviews

Push Notifications & In-App Messaging

Push Notifications

Push Notifications are an effective way to keep users engaged with an app. With cmercury, you can schedule marketing campaigns from the console or send push notifications automatically in response to events by using Automations, for example, when a user enters a Geofence, or via the Push API.

Once enabled and configured, you will be able to send unlimited push notifications to installations of your app on iOS and Android devices, via the native Apple Push Notification Service (APNS) and Firebase Cloud Messaging (FCM).

You can send notifications as part of a marketing campaign from your easy-to-use client portal. You can also Schedule notifications in advance to be sent in the future.

In-App Messaging

In-App Messaging allows you to deliver rich, personalized content to users whilst they are in the app. Use in-app messaging to boost conversion through the on-boarding journey, highlight special offers, ask users to rate your app, subscribe to receive push notifications and much more.

Push notifications and in-app messaging can be combined and used together for maximum effect. Once enabled and configured, you will be able to send unlimited in-app messages to installations of your app on iOS and Android devices. You can then send in-app messages from your client portal. You can also Schedule in-app messages in advance to be sent in the future.

Audience Targeting

cmercury provides different ways to target who you are sending push notifications and in-app messages to.
You can build audience Segments to target specific users of your app based on the user attributes and analytics events you send to cmercury as well as well the analytics data cmercury captures automatically from the install (for example when the app was last opened).

You can use Channels to categorize the content you send and let users subscribe to content relevant to their preferences.
You can define Geofences to target installs within a specific area or within a certain radius of a fixed point on a map (e.g. within 1000m of a retail outlet that is running a promotion).

You can also add Beacons to target installs when they come into proximity of that beacon.

Media Library

Your media library is where you can store images and videos for use in your push notifications and in-app messages and templates. You can also search the Unsplash stock image library.

12

Templates

You can design and save templates that can be re-used when you and your team are sending in-app messages via the console, via the Messaging API or via Automations. Templates can contain dynamic content tags that will be replaced when the message is sent.

13

Automation

Automations allow you to use events as a trigger to fire actions. For example, you can send a push notification when a user enters a geofence or if a user does not complete a journey such as checkout.

14

You can also send push notifications from, and report open rates to, any other backend system using the Push API. Finally, if you use the Backend feature of cmercury, you can send push notifications via Kscripts (for example: when a user has a new chat message or a post gets a new like).

Push Notifications and In-App Messages are available in the Obj-C, Swift, Android, Cordova & Ionic, ReactNative, Xamarin and Unity SDKs.

Getting Started

To enable Push Notifications and In-App Messaging for an app, simply enable the Messaging feature within cmercury, upload your APNS and/or FCM certificates and then integrate an SDK into your app project. As soon as you publish the update to the app stores you will then be able to send push notifications and in-app messages to your users.

Enable Messaging

Add an App
You can add an app for that client by clicking the primary action button. Fill in the name of the App, and optionally, add a brief description and upload an icon. Click “Save” when done.

15

You will now be redirected to the dashboard for that app where you can enable Push Notifications.

Enable Messaging
Select Messaging from the left menu or click the Start button next to Messaging on the App Dashboard.

tyu

You will now see some more information about the Messaging feature.

Click Enable when prompted.

I am text block. Click edit button to change this text. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut elit tellus, luctus nec ullamcorper mattis, pulvinar dapibus leo.

Configure Gateways

In order to send messages to users of your app, you must configure one or more messaging gateways. For mobile push notifications, this means configuring the Apple Push Notification Service (APNS) and/or Firebase Cloud Messaging (FCM), uploading your push certificates to cmercury and then integrating the SDK. For in-app messaging, you simply need to integrate the SDK. There is no additional configuration required for web push notifications.

Click CONFIGURE NOW or, expand ‘Messaging’ in the left menu and select ‘Configuration’.

You will now see the Messaging Configuration screen where you can add your APNS and/or FCM credentials and download the appropriate SDKs for your app.

Click the cog icon next to the platform you would like to configure to open the dialog where you can enter the required information to send push notifications to iOS devices via APNS and/or Android devices via FCM.

APNS Configuration
In order to send push notifications to iOS devices with cmercury, you’ll need to create certificates in the Apple Developer Member Center. The steps to complete this are shown in the video guide.

FCM Configuration
In order to enable push notifications for Android with cmercury, you’ll need to set up an FCM project and configure push for your app. These steps are shown in the following video guide.

Download and Integrate an SDK

You can now download the appropriate SDK(s) for your mobile app by selecting an SDK from the list at the bottom of the Configuration screen.

Follow the integration guide for that SDK to initialize the cmercury client in your app project. Please note that you will need the API Key and Secret Key shown on the App Dashboard to do this.

  • Swift
  • Obj-C
  • Android
  • Cordova & Ionic
  • React Native
  • Xamarin
  • Unity

Checking installs of your App
When you run your app on a simulator or install your app on a device, you can check that the SDK has been initialized correctly by selecting the app and clicking the Installs tab to see the ten most recent installs of your app. Click on an install, click the ‘Push’ tab and click Send Test Push.

Reviewing your Configuration

To review your messaging gateway configuration, expand ‘Messaging’ in the left menu and select ‘Configuration’.
This will show how many installs are subscribed to receive push notifications and how many and users have opted in to receive in-app messages, broken down by platform.

The ‘Push Notifications’ widget is where you can reconfigure the APNS and FCM platforms. This will show an amber, warning alert if the push certificate for APNS is due to expire in under two weeks.

This will show a red critical alert if the certificate has expired! In other words, if you cannot now send notifications to your iOS app! These alerts will be reflected in the App Dashboard.

Click on the cog to see the expiry date of the certificate and upload a new one.

That’s it – you’re all set to start sending notifications to your subscribers!

Dashboard

Once configured, your messaging dashboard will show recent trends in your audience and message history along with a summary of recently created messages.

The Audience chart shows the total number of users for your app along with how many users are reachable by push notifications (have subscribed to receive push notifications) and in-app messaging (have opted-in to receive in-app messages).

The Message History chart shows how many messages have been sent each day, how many of these messages were opened and how many users then unsubscribed from push notifications (or uninstalled the app).

Messages opened within seven days of being sent are shown on the day the message was sent to make it easier to visualize the success of your messaging campaigns. Messages opened more than seven days after a message has been sent are not counted.

Scheduled Messages

You can view messages scheduled to be sent in the future by expanding ‘Messaging’ in the left menu and clicking the ‘Scheduled’ tab.

From here, you can “Edit” the content and data in the notification or “Cancel” a notification or in-app message. Once a notification has been scheduled, it is not possible to change the target for the notification or the schedule. If you wish to do so, “Cancel” the notification and create a new notification with the required target and/or schedule.

Once a scheduled notification or in-app message has been sent (for all timezones if “Device Local Time” was selected), it will no longer be shown under ‘Scheduled’ messages, but will be shown in ‘Sent’ messages.

Sent Messages

You can view all sent push notifications and in-app messages by expanding ‘Messaging’ in the left menu and clicking ‘Sent’.

The messages list shows all sent messages along with summary information of their results. It is split into two tabs:

  • Campaign driven messages, created and sent from your agency console
  • Transactional messages, triggered by automation rules or the Push API

Viewing Results

For each message that has been sent, you will be able to see the message status, the reachable audience of the message, the number of users to whom the message was sent and the number of users that then opened the message.

Click on a message to see more details…

Detailed Results

When you expand a message, you can see the targeting options that were applied to create the audience for the message. Click on the magnifying glass to see the message.

The table will then show you the size of the targeted audience (for example: the number of users in the segment, channel and/or geofence) and how many of them are reachable via the selected messaging gateway (for example how many users have subscribed to receive push notifications or opted-in to receive in-app messages).

As Push Notifications are sent to installs of your app on a device, the table then shows you how many installs are reachable, how many we were able to send to, how many failed (rejected by the APNS or FCM gateway) and how many installs had unsubscribed (or uninstalled the app). The sum of sent, failed and unsubscribed will total reachable.
Finally, the table will show you how many users opened the notification (and on how many devices).

For in-app messages, you can not only see the detailed results and number of users who have opened the in-app message, you can also see detailed results for the push notification that was used to notify the user that a new in-app message is available (if one was sent).

Message Status

The message status can be one of the following:

Analytics

Analytics gives important insights into who is using an app and how engaged they are, to help you make informed decisions on how to drive more downloads, increase retention and conversion. It can be added to any existing app by simply downloading an SDK and following the documentation to quickly and easily integrate this into the app project.

Once you have updated the app, the SDK will automatically send analytics data back to cmercury. When we have received this data, the Analytics Dashboard will be enabled.

The Analytics Dashboard contains six tabs:

The Acquisition tab shows how many new users the app is acquiring and how many have subscribed to receive Push Notifications. If you have enabled App Store Optimisation, the Acquisition tab will also show well the app is performing in the Apple App Store and Google Play Store.

The Audience tab shows – for the last 30 days, 60 days, 120 days, 6 months, 12 months or All Time – how many users are actively using the app, where these active users are located as well as which devices, operating systems and versions of the app they are using.

The Engagement tab shows – for the last 30 days, 60 days, 120 days, 6 months, 12 months or All Time – when during the day and week users are opening the app, how frequently they open the app and how long they typically use the app for.

30

The Retention tab shows how well you are retaining users in the 7 or 30 day period after they installed the app or were actively using the app. Users are grouped into cohorts of date they installed the app or were actively using the app, country or platform allowing you to see how retention varies between cohorts.

The Conversion tab lets you add funnels to track and optimize conversion through key user journeys in your app. With funnels, you can track how many people start different user journeys in your app, how many complete the journey and convert as well as how long it takes on average to do this.

If you have used the App Build Mobile Backend-as-a-Service (MBaaS) feature in cmercury, to store and host data and content for the app, then the Performance tab will show how this is performing, including volume of API calls, average response time and volume of data stored by the app.

The Analytics explorer lets you see all custom analytics events and user attributes uploaded from the app. You can filter by date and group by different event properties or attributes to answer questions on how the app is being used. For example: What is the most viewed screen? Which product category is most popular? How does this vary between male and female users? Etc.

You can also manage schemas, giving attributes friendly names and setting expected types.

Media Library

Your Media Library lets you upload and store images for use in your messages. To access your media library, expand ‘Messaging’ in the left menu and click the ‘Media Library’ tab. Here, you can upload a new image, edit images you have previously uploaded or search the Unsplash stock image library.

Upload a new image

To upload a new image, click the upload primary action button. Click ‘Choose File’ to browse your computer and find the image. Select any tags to help you find the image later or to add a new tag, just start typing and click ‘Create new tag’. Click ‘Upload’ to add the image to your media library.

Edit image tags

To edit the tags on any images you have previously uploaded, simply select the image(s) and click the edit pencil icon to add or remove tags as required. To add a new tag, just start typing and click ‘Create new tag’. Click the tick icon when done. You can either scroll through your library or filter by the tags you have added previously to find the image you are looking for.

Add a stock image

To add an image from the Unsplash stock image library to your media library, click the ‘Stock’ tab and enter one or more keywords in the search box. Scroll through the results and select an image to see more information about it. Once you have found the image, click the camera primary action button to add this image to your media library.

Remove an image

To remove one or more images from your media library, simply select the image(s) and click the trashcan icon

Acquisition

The acquisition tab shows how many new users the app is acquiring and, if you have enabled App Store Optimization, how well the app is performing in the Apple App Store and Google Play Store.

Location Map

The location map shows how new installs over the last 120 days are distributed between different cities and countries. You can click on the map to expand and interact with it (drag, zoom in/out etc). When expanded, click on any location to see how many new installs the app has had in that location in the last 120 days.

cmercury uses GeoLite2 data created by MaxMind and available from http://www.maxmind.com.

New Installs

The new installs chart shows how many new installs the app has had each day over the last 120 days. It can be grouped by country or OS to show how user acquisition compares by geography and between iOS and Android etc.

Total Installs

You can toggle this chart to show the total number of installs of the app and how this has grown over time.

Note that unlike the charts in the Audience tab this chart does not take activity into account and so you should be cautious about how you use the Total Installs figures. However, the chart can still be useful to quickly compare how many new installs of the app there were between two time periods, for example, as a result of a particular marketing campaign or drive to acquire more users.

The widget to the right shows the total number of new installs in the last 30 days and how this compares to and is impacting the total installs of the app for all time.

Push Subscribers

If you have enabled Push Notifications you can see, over the last 120 days, the total number of installs that have subscribed to receive push notifications and how this varies between iOS and Android. Ideally, these charts should closely match the total installs charts above.

The widget to the right shows the number of new subscribers and unsubscribes in the last 30 days. The number of new subscribes should ideally closely match the number of new installs above. If the number of unsubscribes is high, then this will lead to a discrepancy between total installs and push subscribers.

Retention

The retention table shows the count of new installs for each of the last seven days. Installs are grouped in cohorts of the date the app was installed. You can then see what percentage of installs in each cohort were active in each of the seven days after installation.

Click Explore Retention to open the Retention tab and analyse retention for different dates, counts (new installs or active installs), cohorts (date if install or activity, country or OS) and time periods (7 or 30 days).

If you have enabled App Store Optimisation, the acquisition tab will also show how well the app is performing in the Apple App Store and Google Play Store.

Star Ratings

The star rating charts show the average star rating for both your app and competitive apps in both the Apple App Store and Google Play Store over the last 120 days. This not only lets you see if average rating for the app is improving over time, but also how this compares to competitive apps and which of them is most popular.

Keyword Rankings

The keyword ranking charts show how your app ranks for the configured search terms against competitive apps. This shows where your app will appear relative to competitive apps in the results for different search terms and therefore which keywords you need to further optimize the listing for.

Competitive Apps

The table shows the key data about your app and its listing compared to competitive apps.

Note that the number of reviews on the Apple App Store is for the current version only, whereas the number of reviews on the Google Play Store is for all versions.
This can help shape your App Store Optimization strategy by showing how the app compares to competitive apps in terms of:

  • Frequency of updates
  • Download size
  • OS version support
  • Primary category choice
  • Review engagement
  • Rating

Audience

The Audience tab shows – for the last 30 days, 60 days, 120 days, 6 months, 12 months or All Time – how many users are actively using your app, where these active users are located as well which devices, operating systems and versions of the app they are using.

Changing Time Period

By default, the Audience tab shows active installs during the last 30 days. This can be changed by clicking 60 days, 120 days, 6 months, 12 months or All Time as appropriate. All charts in the Audience tab will then update to reflect activity in the selected time period.

Location Map

The location map shows how active installs of the app are distributed between different cities and countries. You can click on the map to expand and interact with it (drag, zoom in/out etc). When expanded, click on any location to see how many active installs the app has in that location in the selected time period.

Note that an install can be counted twice, if it was active in more than one location in the selected time period.

Active Installs

The active installs chart shows the number of daily active installs (for 30 – 60-day periods) or monthly active installs (for 120 day and above time periods). It can be grouped by country or OS to show how active installs compares by geography, or between iOS and Android to compare how these changes over time.

Exploring Data

As with all charts, you can click any series in the legend to temporarily remove this from the chart.

If there are more than six series, the chart will show the top five series (by area) and group the rest into “Other”. To explore the data in “Other”, click the filter icon in the top-right of the chart and then select the five series that you want displayed (the number in brackets represents the total area of the series – in this case the total of each day’s active installs for that series).

Click “Apply” and the chart will update to display the five selected series, again grouping the rest in “Other”. You can do this as often as needed to explore the data.

App Stickiness

The widget to the right shows the current number of daily active installs and how this compares to the total number of active installs in the selected time period. If you have selected 30 days, this will therefore be the number of monthly active installs.

This widget can therefore be used to help calculate how sticky the app is. App stickiness defines what percentage of the app’s monthly active users use the app every day and is important to track to see if your users are using the app as often as you want them to.

App Stickiness is calculated by dividing the number of Daily Active Installs by the number of monthly active installs. For the app shown above, stickiness is just under 17%.

OS Versions

The OS Versions pie charts show how the active install base in the selected time period is distributed between different versions of Android and iOS. An install will only ever be counted once, on the last version of the OS that install was active.

This helps show how up-to-date the active users of an app are with operating system updates and therefore whether or not you need to continue to support older operating systems.

App Versions

The App Versions pie chart shows how the active install base in the selected time period is distributed between different versions of the app. An install will only ever be counted once, on the last version of the app that install was active.

This helps show how up-to-date the active users of an app are with releases and therefore whether or not you need to continue to support older versions of the app or conversely engage users, via a push notification campaign for example, to update to the latest version.

Hardware

The hardware table shows on which devices the app is most active in the selected time period by both manufacturer and model. This gives an insight into how quickly your users are adopting the latest handsets and can shape decisions on representative hardware to purchase for testing and QA.

Countries

The countries table shows from which countries the app is most active in the selected time period. This can be used to report on the success of, or highlight the need for targeted push campaigns to drive up engagement in different countries via audience segments.

Engagement

The Engagement tab shows – for the last 30 days, 60 days, 120 days, 6 months, 12 months or All Time – when during the day and week users are opening the app, how frequently they open the app and how long they typically use the app for. If you have enabled Push Notifications it will also show how many push notifications have been sent and opened.

Changing Time Period

By default, the Engagement tab shows active installs during the last 30 days. This can be changed by clicking 60 days, 120 days, 6 months, or 12 months as appropriate. All charts in the Engagement tab will then update to reflect activity in the selected time period.

Session Definition

cmercury records sessions based on application foreground and background events. When an app enters the background, cmercury will wait for a configurable idle period. If there are no more foreground events during that idle period, the current session will be closed.

You can configure the idle period to suit your app’s use-case. By default, the idle period is 40 seconds of inactivity. The idle period does not count towards session duration calculations.
To adjust the idle period, please see the appropriate integration guide for your SDK (e.g. Android).

Session Distribution

The session distribution bubble chart shows when during the day and on which days of the week the most sessions occur (i.e. when during the week is your app used the most). The larger the circle, the more sessions there were started in that hour. Hover over any circle to see how many sessions were started in that hour.

Sessions are recorded according to the local time of each device on which the app is installed.

Session Frequency

The session frequency chart cohorts’ users into five equal-width bins according to how many sessions they had during the time period. The width of the bins varies depending on the maximum number of sessions per user in that time period. This enables you to see both the most common usage profile for your app and how many users fall into each usage profile (e.g. how many whales, dolphins and minnows an app has).

Sessions Per Day

The sessions per day chart shows how many sessions occurred for each day in the time period, allowing you to quickly see trends of how often the app is being used.

The widget to the right shows the average number of sessions per day for the time period.

Session Length

The session length chart shows the median session length for each day in the time period, allowing you to quickly see trends of how long the app is, on average, used for.

The widget to the left shows the median session length for the selected time period.

Push Open Rates

If you have enabled Push Notifications you can see the total number of notifications that have been sent and how many of these have been opened in the selected time period. You can compare this to the active installs chart above to see the impact Push Notifications has had on activity.

57

The widget to the right shows the average open rate in the selected time period allowing you to see how these changes over time.

Retention

The Retention tab shows how well you are retaining users in the 7 or 30 day period after they installed the app or were actively using the app. Users are grouped into cohorts of date they installed the app or were actively using the app, country or platform allowing you to see how retention varies between cohorts.

57

Default Behaviour

By default, the Retention tab will show you the count of new installs for each of the last seven days. Installs are grouped in cohorts of the date the app was installed. You can then see what percentage of installs in each cohort were active in each of the seven days after installation.

The higher the retention for a cohort on a given day, the darker the shade of the background of each cell in the table, allowing you to very quickly spot patterns.

Configuration Options

There are a number of different configuration options to let you drill down and analyse how well the app is retaining its user base.

Start Date
Click on the Start Date to choose the first date from which you want to analyse retention.

Count
Click on Count to analyse retention for users who had just installed the app in the date period selected (New Installs) or users who were actively using the app in the date period selected (Active Installs).

Cohort
Next, click on Cohort to choose what cohorts to group installs into. By default, installs are grouped in cohorts of date (i.e. the date the app was installed or the date the app was active). However, you can also select Country or OS.

Period
Select the period you wish to view retention over. By default, this is 7 days after the app was first installed or was actively used. However, you can change this to 30 days in which case you will see retention on days 1, 3, 5, 7, 14, 21 and 30.

Absolute Numbers
Finally, you can toggle absolute numbers to see the actual count of installs in each cohort that actively used the app on each as opposed to the percentage of installs.

Conversions

The Conversion tab lets you add funnels to track and optimize conversion through key user journeys in your app. With funnels, you can track how many people start different user journeys in your app, how many complete the journey and convert as well as how long it takes on average to do this.

Funnels also show you where in the journey users’ drop-off and how long it takes to progress through each step so you can optimize the user journey to increase conversion and decrease the time taken.

To use funnels, your app must send custom analytics events to cmercury. See the integration guide for the appropriate SDK(s) for your app. For example: Swift SDK and Android SDK.
When you run your app on a simulator or install your app on a device, you can check that the SDK is recording events correctly by selecting the app and clicking the “Installs” tab to see the ten most recent installs of your app. Click on any install and then click on the “Events” tab.

Alternatively, to see counts of all analytics events, including system events such as opened a push notification, recorded by installs of the app in the last 30 days, expand ‘Analytics’ and click ‘Explore’ in the left menu. For comparison, the total number of sessions in the same period is shown.

Adding a Funnel

To add a funnel, select the App and then in “Analytics” go to the “Conversion” tab and click the Add icon. Give the funnel a title and a description.

If you have used user association in your app, toggle the “Group by user” option. This will associate events by user allowing them to convert even if they complete steps on different devices (e.g. phone and tablet). If you have not used user association, events are associated by install (i.e. to convert, all steps must be completed on same device).

To group by user, your app must associate a user with the cmercury install id. See the integration guide for the appropriate SDK(s) for your app. For example: Swift SDK and Android SDK.

Adding steps to a Funnel
A funnel must have two or more steps. Click “Add Step” to add a step to your funnel. Select the analytics event from the drop-down menu and then give the event a friendly name (that will be displayed when you visualize the funnel).

Repeat this process to add other steps to the funnel. You can re-order steps by clicking the anchor icon and dragging the step to a new position. You can delete steps by clicking the trash can icon.

Repeat this process to add other steps to the funnel. You can re-order steps by clicking the anchor icon and dragging the step to a new position. You can delete steps by clicking the trash can icon.

Click “Save” when done to explore conversion.

Viewing a Funnel

To view a funnel, select the App and then in “Analytics” go to the “Conversion” tab. Each funnel will be listed with a summary showing:

  • How many users/installs entered the funnel (completed the first step) in the last 30 days
  • How many users/installs converted (completed all steps) in the last 30 days
  • The conversion rate (percentage of users/installs)
  • The predicted average time through funnel (see below)

Exploring Conversion
To explore conversion in more detail, click “Explore” to see how many users/installs completed each step of the funnel, the percentage of users who progressed to the next step and the average time taken to do this.

Scroll down to see a summary of the funnel:

  • How many users/installs entered the funnel (completed the first step) in the last 30 days
  • How many users/installs converted (completed all steps) in the last 30 days
  • The conversion rate (percentage of users/installs)
  • The predicted average time through funnel (see below)
72

There is also a table showing, for each step:

  • The percentage drop-off from the previous step
  • The absolute and percentage conversion from the previous step
  • The average time taken to convert from the previous step

Predicted average time
The predicted average time through the funnel is the sum of the average times taken to complete each step in the funnel (not just the average times of only those who completed the funnel). This lets you see which steps are taking all users a long time to complete and can likely be optimized.

To optimize a user journey to improve conversion, start with the steps that have the highest drop-off and then the steps that take the longest time to complete. Consider how each step can be improved.

Filtering a Funnel
By default, the funnel shows how many users/installs entered and completed the funnel within the last 30 days. To change this, click the settings cog icon.

First, choose how to filter the funnel:

  • Entered and completed within date range
  • Entered within date range and completed within period
  • All Time (no filter)

Entered and completed within date range
If you have selected “Entered and completed within date range” you must then select the start and end date of the date range. This can be useful for measuring a time-limited promotional campaign.

Note that a user/install must complete all steps within the date range to count towards conversion. If they enter in the date range but do not complete one or more steps until after the end date, they will contribute to the drop-off after the last step they completed before the end date.

Entered within date range and completed within periodntered and completed within date range

If you have selected “Entered within date range and completed within period” you must then select the start/end date of the date range and the maximum period of time (minutes, hours or days) within which they can convert. This can be useful for measuring conversion of leads generated within a calendar month over different time periods (for example).

Note that a user/install must complete all steps within the maximum time period after they entered the funnel (completed the first step) to count towards conversion. If they enter in the date range but do not complete one or more steps until after the maximum time period, they will contribute to the drop-off after the last step they completed within the maximum time period.

Click “Apply” to apply these new filters to the funnel.

Grouping
By default, the funnel shows how many users/installs entered and completed the funnel within the last 30 days. To see how different cohorts compare, click the settings cog icon and under ‘Group By’ select a dimension.

Grouping
By default, the funnel shows how many users/installs entered and completed the funnel within the last 30 days. To see how different cohorts compare, click the settings cog icon and under ‘Group By’ select a dimension.

Click “Apply” to apply to redraw the funnel and compare cohorts.

Operating system is the only dimension currently available to cohort users/installs but it will soon be possible to cohort by other dimensions such as app version, user attributes or metadata from the events themselves.

Split by group
The table will now be split by group showing the percentage drop-off, absolute and percentage conversion and the average time taken to convert from the previous step for that group throughout the entire funnel.

This enables you to see the performance through the entire funnel for each group.

Split by step
To compare the relative performance of different groups at each step, click the “Split by step” toggle. The table will now show for each step, the percentage drop-off, absolute and percentage conversion and the average time taken to convert from the previous step for each group.

To change the table back to see the performance through the entire funnel for each group, click the “Split by group” toggle.

Changing Visualization
By default, the funnel is visualized as a horizontal bar chart. To change the visualization to a literal funnel, click the “Funnel” toggle.

To change the visualization back to a horizontal bar chart, click the “Bars” toggle.

Targeting Drop-Offs

You can target users who do not complete a user journey or funnel within a certain period of time, for example to encourage users to complete the onboarding flow and retain them within the app or to target users who abandon their shopping cart. Select ‘Drop-off triggered’ as the trigger event.

To do this, click the automation (lightning) icon next to the step that you want users to complete to create a new automation with a rule that has the funnel drop-off trigger pre-populated.

Give the automation a name and select the timeout when the trigger should fire if a user does not complete the funnel step within that time of the previous funnel step. You can set the timeout in minutes, hours or days.

Click ‘Create’ to create to define the audience and add an action such as sending a push notification.

Editing a Funnel

To edit a funnel name or description and/or edit the steps in the funnel, select the App and then in “Analytics” go to the “Conversion” tab. Expand the context menu and select “Edit”.

Remember to save any changes or click back to discard.

Deleting a Funnel

To delete a funnel, select the App and then in “Analytics” go to the “Conversion” tab. Expand the context menu and select “Delete” then click “OK” when prompted.

Remember to save any changes or click back to discard.

Performance

If you have used the App Build Mobile Backend-as-a-Service (MBaaS) feature in cmercury, to store and host data and content for the app, then the performance tab will show how this is performing.

Remember to save any changes or click back to discard.

API Traffic

The API Traffic chart shows the volume of API calls made by installs of the app to cmercury each day over the last 120 days.

Processing Time

The API Response chart shows the average processing time, in seconds, of API calls made each day over the last 120 days. If this is increasing, then you may need to revisit the data model for your app and/or consider adding indexes where appropriate.

Database Storage

The Database size chart shows, for each of the last 120 days, the cumulative amount of data stored in cmercury by users of the app.

Explore

The Analytics explorer lets you see all custom analytics events and user attributes uploaded from the app. You can filter by date and group by different event properties or attributes to answer questions on how the app is being used. For example: What is the most viewed screen? Which product category is most popular? How does this vary between customers and non-customers? Etc.

You can also manage schemas, giving attributes friendly names and setting expected types.

Events

To explore analytics events from an app, click ‘Explore’ in the left menu and the ‘Events’ tab. This will show the count of all analytics events, including system events such as opening a push notification, as recorded by Android and iOS installs of the app in the last 30 days. For comparison, the total number of sessions in the same period is shown.

Changing Counts

By default, the table will show the number of occurrences of each event, with the number of sessions in the same period shown for comparison.
To change the table to show the number of installs on which an event has occurred, click ‘Count By’ and select ‘Installs’. The total number of active installs in the same period will now be shown for comparison.

If you are using user association in the app, you can change the table to show the number of users for which an event has occurred, click ‘Count By’ and select ‘Users’. The total number of users will then be shown for comparison.

Filtering and Grouping

To change the period for which events are shown, click the ‘Start Date’ and ‘End Date’ pickers.
You can also group events by one or more properties and/or user attributes. For example, if you have a screen View event, with the screen name as a property, you can group events by this property to see which screens are most popular.

You can add additional groupings as required. For example, if you have an isCustomer user attribute and want to see how many customers versus non-customers have viewed a particular screen, you can add another grouping by this attribute.

Hide System events

To hide system events such as opened a push notification, click the “Hide System Events” toggle.

To show system events again, click the “Show System Events” toggle

Export to CSV

To export the events (with the current filtering and grouping) to CSV, click the download icon.

To show system events again, click the “Show System Events” toggle

Attributes

If you are using user association in the app and associating attributes with users, you can explore these attributes by clicking ‘Explore’ in the left menu and the ‘Attributes’ tab. This will show how many times the attribute has been set on Android and iOS installs as well as the total number of installs and users for which the attribute has been set.

If you click on an attribute, you can then see the discrete values for that attribute along with counts of installs and users with that value.

Only scalar types with less than 10 unique values can be explored. For more details on attribute types see the Schemas section below.

Export to CSV
To export the attributes to CSV, click the download icon.

Schemas

If you are using user association in the app and associating attributes with users, you can see all of the distinct attributes by clicking ‘Explore’ in the left menu and then the ‘Schemas’ tab. This will show each attribute along with its detected type and expected type.

Friendly names
To give an attribute a friendly name (that will be shown when using the attribute to filter or group by) simply type a new name in the field and click ‘Apply’ when done.

Types
cmercury will automatically detect the type of each attribute based on the values it contains. The type will determine if and how the attribute can be used to group by or filter segments, for example by showing appropriate comparison operators. Available types are:

  • number
  • boolean
  • string
  • array
  • object
  • mixed

If you want to set an attribute to a date, for example: a user’s birthday or subscription start date, use a string type and set the date to an ISO8601 compatible string. This will allow you to use the gt and lt comparison operators for targeting in segments.

If attributes contain values of different types, cmercury will try to use a type that accommodates all values. For example if one build of an app uploads an attribute as a scalar type (e.g. a boolean), but another build (e.g. on a different platform) uploads the same attribute as different scalar type (e.g. a number), then cmercury will use the string type for that attribute (and when filtering by that attribute show the ‘Includes’ operator rather than numeric operators).

If scalar and non-scalar values are observed in the same attribute, cmercury will use the mixed type for that attribute unless you manually set the expected type of that attribute.

Expected Type
To set the expected type of an attribute (for example to force cmercury to treat the attribute in the example above as a number), simply select the expected type from the drop down and click ‘Apply’.

cmercury will now treat that attribute as the expected type and show the appropriate operators for that type when filtering by that attribute. Any users where the attribute is not of the expected type will be excluded from any segments using that attribute as a filter.

Analytics API

Analytics data can be accessed via our public API.
Accessing the API

All analytics endpoints can be found at https://analytics.app.delivery/api/v1
Generating an access token

To access the API data, you must generate an access token, from within the Analytics service in the Agency Console under the Explore section there is an API tab.
From this section you can manage existing tokens, revoke their access, and create new ones.

Click the add button to create your first access token.

Authentication
Any access to the following api endpoints requires authentication via the authorization header, using a valid access token as a bearer.
Authorization: Bearer [access token]
The Accept header should also be set for application/json.

Required querystring parameters
All sample requests in the following examples are assumed to have these parameters included.
From / To – ISO8601 formatted date filter, for new installs and all installs this relates to the dates they were created between. For active installs the install must have been used at least once to be counted for any given day.

simulatorFilter – Filter installs running on a simulator can be one of:

  • Return all installs
  • Return only installs running on a simulator
  • Return only installs running on a real device

targetTypeFilter – Filter out installs using release and / or debug builds

  • Return all installs
  • Return only installs running a debug build
  • Return only installs running a release build

Resource Types
References to the resourceType} within the path refers to the type of installs to be counted, can be one of:

new-installs Installs created within the period
active-installs Installs that have interacted with cmercury within the period
all-installs Total installs at the end of the period

Available APIs
Install counts by series

/api/v1/{resourceType}/{series}

This API returns the count of the type of install grouped by the specified series, ordered by the install count descending.
Series can be one of:

  • countries
  • cities
  • os-versions
  • app-versions
  • devices

For example /api/v1/active-installs/os-versions will return

Install counts by series over time

/api/v1/{resourceType}/{grouping}/{series}
This API returns the count of the type of install grouped by the grouping type, then the specified series.

Series can be one of:

  • countries
  • os type

Grouping can be one of:

  • daily
  • monthly

For example /api/v1/active-installs/daily/countries will return

Event counts

/api/v1/events
This API returns the number of occurrences of analytics events received from devices, with extra querystring parameters you can select what type of counting, grouping of counts, and filter out cmercury generated system events. All the count types return counts per the operating system that triggered the event, in addition to the total.

countBy can be one of:

  • events
  • installs
  • users

Events will count the number of times the event has occurred; installs will count the number of unique devices which have raised the event and users will count the distinct users who have raised the event within the period.

hideSystemEvents can be one of:

  • true
  • false

groupBy is an optional parameter, and if supplied allows grouping on a user attribute or event data property:

  • user.*would group by a user attribute, for example user.isCustomer
  • data.*would group by a event data property, for example data.screenName

Groupings can be multi-dimensional and combine with a comma separated list of fields, for example: groupBy=user.isCustomer,data.screenName.

The example query /api/v1/events?countBy=events&hideSystemEvents=false? will return

Session data

/api/v1/sessions/{resourceName}
These resources describe aspects of the active users’ sessions, for example their distribution over localized time of day or their duration.
Resource Name can be one of:

    • time-of-dayFor each day of the week show how many sessions for localized hour of day
    • distributionFor equally weighted buckets show how users are grouped in terms of number of sessions.
    • dailyCount of sessions per day
    • summaryAverage session duration and average sessions per day
    • durationMean session length grouped by day
    • duration-filteredMean session length grouped by day, filterable on user attributes

For example, /api/v1/sessions/distribution will return

When using the filtered resources, the following parameters can be provided.

    • Filters

Provided as an array of key value pairs where the key is the attribute and the value are the filter, for example:

filters[user.lifetimeValue]=105&filters[user.isCustomer]=true

Any responses will match the unfiltered resource.

Retention

/api/v1/{resourceType}/retention

This resource describes how users are making use of the app over a period of days, showing how often and when users are likely to re-engage, this is available for new-installs and active-installs only.

Extra querystring parameters are required for each request.
cohort can be one of:

time
countries
os-types

periods describe the day increments between results for example 1,2,3,4,5,6,7 would give a complete 7-day window.

For example, new-installs/retention?cohort=time&periods=1,2,3,4,5,6,7 will return

CRM API

cmercury has a RESTful API that allows you to manage users’ attributes for future targeting with segments and/or the Messaging API.

Headers

Please ensure that you set the following headers in your request:

Content-Type: application/json
Accept: application/json

Authentication

The cmercury CRM API authenticates via HTTP Basic Auth using your app’s API Key as the username and your Server Key as the password (in the Authorization header). Both of these are available from the App Dashboard in your Agency Console.

Set attributes

PUT https://crm.kumulos.com/v1/users/{user-id}/attributes

Payload
Attributes can then be passed in as a raw JSON object in the body.

Please ensure that you are using the same user ids as your mobile app is passing into the associateUserWithInstall() method as a new user will be created the specified user id if one does not already exist.

Also, please note that last write wins, so this call will overwrite any attributes set by your mobile app (in the associateUserWithInstall() method) and vice versa.

Sample cURL

Sample PHP

Responses

401 Unauthorized
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity
Your request was either unparsable or contained invalid JSON. The response body will return a JSON object describing what keys were not present or had invalid values.

200 OK
Your request was processed. A new user will have been created with the specified user id, if one did not already exist, and attributes set. The response body will contain a JSON object describing the user that was created or updated as a result.

Delete attributes

DELETE https://crm.kumulos.com/v1/users/{user-id}/attributes

Sample cURL

Sample PHP

Responses

401 Unauthorized
Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

400 Bad Request
Your request was valid but a user with the specified user id could not be found.

204 No Content
Your request was processed and the attributes have been deleted for the specified user.

Crash Reporting & Diagnostics

To enable Crash Reporting & Diagnostics for an app, enable the Diagnostics feature within cmercury, add monitoring checks to track the performance of the services your app depends on to function and integrate an SDK into your app project to track unhandled exceptions in your app.

Add Monitoring Checks

To start tracking the performance of the services your app depends on to function, add a monitoring check for each of the API Endpoints your app relies on and communicates with. Select “Monitoring Checks” and then click the “Add a Monitoring Check” or the Primary Action Button.

Use the wizard to enter details of the API Endpoint (URL, Request Method etc), any HTTP Headers (e.g. Authorization), Warning and Critical Thresholds for Response Time and optionally a JSON schema against which the payload will be validated. Then, within 5 minutes, you will see detailed results from around the world.

Download and Integrate an SDK

To start tracking unhandled exceptions in your app, download and integrate an SDK into your app. Select the appropriate SDK(s) from the list to view the integration guide for and download that SDK.
Follow the integration guide for that SDK to initialize the cmercury client in your app project. Please note that you will need the API Key and Secret Key shown on the App Dashboard to do this.

• Swift
• Obj-C
• Android
• Cordova & Ionic
• ReactNative
• Unity

Crash reporting is not enabled by default. To enable this feature, simply modify your cmercury initialization to include enabling crash reporting.
Note that crash reporting is not available whilst connected to a debugger, but it does work with debug builds.

Checking installs of your App
When you run your app on a simulator or install your app on a device, you can check that the SDK has been initialized correctly by selecting the app and clicking the Installs tab to see the ten most recent installs of your app. Click on any install to see more information.

That’s it! Unhandled exceptions that lead to crashes (along with any caught exceptions you choose to report) will now be recorded automatically and shown in your console. However, we recommend you trigger a crash to verify everything is working.

Diagnostics Dashboard

Once enabled, the Diagnostics Dashboard gives you complete visibility of the technical performance of your app and all the services it depends on to function so you can be proactive and minimize the impact of any problems on your audience such as crash reports caused by an API Endpoint outage.

103

The Dashboard will update every 5 minutes, but clicking the refresh button will update immediately.

Overview

The widgets at the top of the Dashboard give you an immediate overview of the health of your app.

By default, these widgets will show the health of your app over the last 24 hours, but you can change this to the last 7 days (1 week), 30 days (1 month) or 90 days (1 quarter). Alternatively, select Custom and enter a start and end date to see this over a period of time up to 180 days (6 months).

Uptime shows the percentage of time that all of the API Endpoints you are monitoring were Available during the selected time period as well as the absolute downtime (the duration of time where one or more API Endpoints had an Outage) over the same time.
Sessions shows the percentage of Crash Free Sessions in the selected time period as well as the absolute number of sessions that experienced a crash during that time.

Installs shows the percentage of Crash Free Installs in the selected time period as well as the absolute number if installs that experienced one or more crash during that time.

Monitoring Checks

The Monitoring Checks table shows the current status of the API Endpoints you are monitoring.

For each API Endpoint, you can see the overall Endpoint status as well as the status from each data centre. You can see how long the Endpoint has been in that status and when it was last tested. Click on any Endpoint to see more detailed test results.

At the top of the table you can see the count of Endpoints by status. API Endpoints are ordered in the table by Status with those Endpoints with an Outage or Partial Disruption appearing first. The table will show up to 5 API Endpoints. Click on the link at the bottom to view the status of all Endpoints.

Recent Issues

The Recent Issues table shows those issues where a crash has occurred recently.

For each issue, you can see when it was first opened, how many installs it is affecting, how many times it has occurred and when it last occurred. The spark line will show the trend of occurrences over the last 24 hours so that if you have an API Endpoint outage, you can quickly see any crash reports that are occurring because of this.

The table will show up to 10 Issues. Click on the link at the bottom to view all Issues.

API Monitoring Checks

Monitoring Checks to track the performance of the services your app depends on to function. Are all API Endoints reachable? Returning the correct response code? Returning data to your app in the expected format? And how long do they take to do this? Monitoring checks will alert you to any problems before they impact your audience.

Select the App, expand “Diagnostics” and select “Monitoring Checks” in the left hand menu.

If you have a lot of endpoints you want to monitor, click “Contact Us” to arrange to send us a Postman collection or Swagger/OpenAPI spec and we’ll import them for you.

Add a Monitoring Check

To start monitoring an API Endpoint, click the primary action button.
Give the endpoint a descriptive name, select the HTTP Method (GET, POST, PUT, DELETE or PATCH), enter the URL and any query parameters (as key, value pairs). Click “Next” when done.

Add any HTTP headers to the Request such as an Authorization header and click “Next”.

In addition to testing that the API Endpoint is Reachable and returning a successful 2xx Response Code, the Monitoring Check will test how long the API Endpoint takes to respond to the HTTP Request from each Data Centre. Specify a Warning and Critical threshold for Response Time in milliseconds.

If you also want the Monitoring Check to test that the payload returned validates against a JSON schema, click the “Add Schema” button.

You can enter a JSON schema manually into the right-hand pane, but it is simpler to infer the JSON schema from the actual response body of the API Endpoint itself. Click “Fetch Payload” to execute the HTTP Request and then “Infer Schema” to derive the JSON schema from the response. You can manually edit the schema if required. Click “Save JSON Schema” when done and then “Next”.

You can now review everything entered and click “Back” to make any changes. Click “Save” to add the Monitoring Check.

The Monitoring Check will now be added and results will appear within the next 5 minutes.

View Detailed Results

To view detailed results, click on the Endpoint in either the table in the Diagnostics Dashboard or the Monitoring Checks page (expand “Diagnostics” and select “Monitoring Checks” in left hand menu).

Endpoint Status

The overall Endpoint Status and how long the Endpoint has been in that status is shown at the top.

For the Endpoint Status to be ‘Available’ (green), all tests from all Data Centers must be OK.

If a test from one Data Center is Crtical, the Endpoint Status will be ‘Partial Disruption’ (yellow) as the problem is localised to one region (i.e. the other Data Centers are OK for the same test).

If a test from two or more Data Centers is Critical, the problem is obviously more widespread and the Endpoint Status will be ‘Outage’ (red).

Endpoint Status Description
Available All Tests from all Data Centers are OK
Partial Disruption One Data Center is Critical (for any Test)
One or more Data Centers are Warning (for Response Time)
Outage Two or more Data Centers are Critical (for same Test)

Uptime

Uptime shows the percentage of time that the Endpoint Status was Available during the selected time period as well as the absolute downtime (when Endpoint Status was Outage) over same time.

By default, this will show the last 24 hours, but can be changed to the last 7 days (1 week), 30 days (1 month) or 90 days (1 quarter). Alternatively, select Custom and enter a start and end date to see this over a period of time up to 180 days (6 months).

Tests

Detailed results for each Test from each Data Center are shown.

Data Centers are ordered in the table by Status with those Data Centers that have a Critical test or a Warning test appearing first. For each Data Center, the detailed results of each test will be shown.

Test Status Description
Reachable OK HTTP Request successfully made
Critical Network error prevented HTTP Request
Response Code OK Response Code was 2xx (Success)
Critical Response Code not 2xx e.g. 4xx (Client Error) or 5xx (Server Error)
Response Time OK Response received before Warning Threshold (e.g. 3500 ms)
Warning Response received after Warning but before Critical Threshold
Critical Response received after Critical Threshold (e.g. 5000 ms)
Payload OK Response body passed validation against saved JSON schema
Critical Response body failed validation against saved JSON schema

Any tests that are Critical will be shown in red. Hover over that test to see a tool-tip with the reason such as the network error (e.g. TLS handshake failed) or the JSON path that failed validation.

Response Time

The chart shows how long on average it took each Data Center to receive a response to the HTTP Request from the Endpoint along with the worst Endpoint Status for each interval on the chart.

By default, the chart will show the last 24 hours at 15 minute intervals. This can be changed to the last 7 days (with hourly intervals) or 30 and 90 days (with daily intervals). Alternatively, select Custom and enter a start and end date to see this over a period of time up to 180 days (6 months).

Hover over any interval on the chart to see the average response time for each data centre during that interval as well as the worst Endpoint Status during that interval.
Soon you will be able to drill down and see how the Response Time is comprised i.e. how much time was spent on DNS Resolution, Transfer etc and how this varies over time.

As response times shown are the average for that interval, it is possible that the EndPoint Status can be Partial Disruption or Outage caused by a slow Response Time for a test that exceeds a threshold, but that the average for the interval is under the threshold. In which case, look at the corresponding incident to see more details.

Incidents

Incidents show any current problems as well as a history of all past problems with an API Endpoint.

If a Test is not OK, an Incident will be opened and will remain open until that Test is OK for all Data Centers. However, if the same Test is not OK from multiple Data Centers, then only one Incident will be opened. Click on the Incident to see a timeline for each Data Center and hover over to see exact failure reason.

New incidents will be opened for the most important test only. For example: if an Incident is opened because Response Code is Critical, an Incident will not be opened for Payload validation etc.

However, if an Incident is already open for one Test e.g. Response Time and later a more important Test e.g. Response Code becomes Critical, the Response Time Incident will remain Open and a new Incident for Response Code will also be opened. The Response Code Incident will be closed when Response Code is OK for all Data Centers and then the Response Time Incident will be closed when Response Time is OK for all Data Centers.
Open Incidents will show the current worst Test Status for any Data Center whereas Closed Incidents will show the worst Test Status at any point during the Incident.

Edit a Monitoring Check

To edit any of the Endpoint details (such as request headers), warning and critical thresholds or the JSON schema, first select the App, expand “Diagnostics” and select “Monitoring Checks” in the left-hand menu. Expand the context menu for that Monitoring Check and select “Edit”.

Remember to save any changes or click the back arrow at any point to discard.

Delete a Monitoring Check

To stop monitoring an API Endpoint, select the App, expand “Diagnostics” and select “Monitoring Checks” in the left-hand menu. Expand the context menu for that Monitoring Check, select “Delete” and then click “OK” when prompted.

Overview

Once configured, the overview tab will quickly show you how often your app is crashing, where and on what devices as well as how many installs of your app are crash free.

Filtering Dashboard

If you have both iOS and Android versions of your app, then your Crash Dashboard is a single-pane-of-glass for all issues affecting your apps. However, you can use the drop-down menus at the top of the Dashboard to view the trends over different time periods or for specific operating system versions only.

You can filter issues by:

• Type (Fatal or Non-Fatal)
• Status (New, In Progress, Blocked, Fixed, Unable to Reproduce, Rejected)
• Operating System version
• Timeframe (Past 30 days, Past 60 days or Past 90 days)

You can multi-select options from each drop-down. Click “Apply” to update the Dashboard.

Location Map

The location map shows how crashes are distributed between different cities and countries. You can click on the map to expand and interact with it (drag, zoom in/out etc). When expanded, click on any location to see how many crashes have occurred.

Affected Installs

The affected installs chart shows how many installs have experienced at least one or more crash. Hover over any point to see absolute numbers.

Crash Free Installs

The widget shows the percentage of crash free installs and the total number of installs of the app.

Hardware

The crashes by hardware table shows the manufacturer and model on which crashes are occurring allow you to quickly identify any trends and on which devices to test. For each model, the table shows:

• The number of crashes that have occurred and what percentage of all crashes that constitutes
• The number of affected installs and what percentage of the active installs of that model have experienced at least one crash
• The number of installs that are active on that model and what percentage of total active installs that constitutes

Integration status

The status of Slack, Microsoft Teams,Trello and Jira integrations are shown, if they have been configured.

Issues

Once configured, any unhandled exceptions that lead to crashes (along with any caught exceptions you choose to report) will be recorded automatically and shown in the Crash section for your app. Click on the app, select “Diagnostics” in the left hand menu and then “Crash Reporting” before clicking on the “Issues” tab…

Each issue will show the platform (iOS or Android) on which the issue occurred, when the issue was opened (i.e. when the crash first occurred), how many installs are affected and how many device models are affected.

Filtering Issues

If you have both iOS and Android versions of your app, then all issues affecting your apps will be shown here, in a single-pane-of-glass. However, you can use the drop down menus at the top of the Issues view to filter the list of issues shown.

You can filter issues by:

• Type (Fatal or Non-Fatal)
• Status (New, In Progress, Blocked, Fixed, Unable to Reproduce, Rejected)
• Operating System version
• Timeframe (Past 30 days, Past 60 days or Past 90 days)

You can multi-select options from each drop-down. Click “Apply” to update the list of issues.

Viewing an Issue

To view more details about an issue, select that issue in the list.
The panel to the right-hand side will show how many installs have been affected, how many occurrences there has been of this crash, as well as a breakdown of operating systems and versions of your app affected. It will also show when the issue first occurred and when the issue last occurred.

Multiple occurrences of the same crash are grouped together in the same issue. This lets you prioritize the issues that are having the biggest impact on your user-base (i.e. those issues with the highest number of affected installs).
The middle pane shows the stack-trace for the latest occurrence of an issue as well as important information about the install that this occurrence of the crash affected, including:

• Device model (or if this occurrence was on a simulator)
• App Version
• Location when issue occurred
• Date and time the issue occurred
• Free memory on device when issue occurred (iOS only)
• Locale setting of devices when issue occurred

You can navigate between occurrences of the same crash using the Prev and Next buttons to view other stack traces and information about the install that those occurrences of the crash affected.

For issues that occur on Android, you can also view the system logs (providing your app has this permission).

Finally, you can view all status changes and any comments left on an issue by your team in the bottom pane.

Updating an Issue

You can update the status of an issue by clicking the drop down at the top right of the middle pane and selecting a new status.

Status changes are saved automatically and recorded in the comments section of the issue.

Issue Status and Workflow

Issues can be in one of three open status types (New, In Progress, Blocked) or one of three closed status types (Fixed, Unable to reproduce, Rejected). The table below describes each status as well as what happens when there is a new occurrence (as this depends on the status of that issue).

State Status Description New Occurrence?
Open New A new issue requiring attention. Occurrence will be added to same issue.
Open In Progress Issue has been acknowledged and a fix is in progress. Occurrence will be added to same issue.
Open Blocked Fix cannot be progressed at this time e.g. further information required. Occurrence will be added to same issue.
Closed Fixed Issue has been resolved. Occurrence will be added and issue re-opened to New status.
Closed Unable to reproduce Unable to identify cause and attempts to reproduce have been unsuccessful. Occurrence will be added and issue re-opened to New status.
Closed Rejected Issue is not being fixed e.g. only affected older operating systems Occurrence will be added only. Issue remains in Rejected status.

If there are one or more issues in an open state, the App Dashboard will show an amber, warning alert for Crash. If one or more of these issues have New status, the App Dashboard will show a red, critical alert.

Commenting on an Issue

When working on an issue or updating the status of an issue, it is good practice to leave a comment for your team and/or your future self-explaining what you are doing.

Merging Issues

Multiple occurrences of the same crash are grouped together in the same issue. This lets you prioritize the issues that are having the biggest impact on your user-base (i.e. those issues with the highest number of affected installs).

However, should you decide that two issues that are not grouped together are in fact caused by the same crash, then you can manually merge issues. From the context menu for the duplicate issue, select “Merge”

Enter the number of the issue you want to merge into and click “Merge”

Integrations

cmercury can integrate with Slack, Microsoft Teams, Trello and Jira so your team can be immediately notified when new crashes occur, and then track the development and testing of the fix in the existing tools you are already using to manage your development process.

Slack

You can configure cmercury to send a notification to a Slack when a new issue is raised by adding an Incoming Webhook as follows.

Create Incoming Webhook in Slack

Visit the Slack App Directory and search for “Incoming Webhooks”

Select the channel you wish to receive the notifications for this app or create a new channel and then click “Add Incoming Webhooks integration”

Scroll down to view webhook settings and copy the URL to the clipboard.

You can also give the webhook a description, a friendly name and customize the icon. Once you are happy with the preview of the message as shown, click “Save Settings”.

You should see a message in the slack channel that a new integration has been added.

Configure Webhook URL in cmercury

Click on the app and then select Crash in the left hand menu to open the Crash Dashboard for that app. Click on the settings cog next to Slack in Integrations on the right and paste in the Webhook URL copied from Slack earlier.

Click “Configure” and you should see that Slack integration is now configured.

Now, when a new issue occurs, your team will be immediately notified in Slack.

To ensure you are notified of the issues that require your attention, cmercury will only notify you when a new issue is raised or when an issue you previously fixed reoccurs. cmercury will not notify you when there is another occurrence of an issue you already know about and are working on as this could be noisy depending on the size of your install base.

Microsoft teams

You can configure cmercury to send a notification to Microsoft Teams when a new issue is raised by adding an Incoming Webhook connector as follows.

Create Incoming Webhook in Microsoft Teams

In Microsoft Teams, choose More options (⋯) next to the channel name and then choose Connectors.

State Status Description New Occurrence?
Open New A new issue requiring attention. Occurrence will be added to same issue.
Open In Progress Issue has been acknowledged and a fix is in progress. Occurrence will be added to same issue.
Open Blocked Fix cannot be progressed at this time e.g. further information required. Occurrence will be added to same issue.
Closed Fixed Issue has been resolved. Occurrence will be added and issue re-opened to New status.
Closed Unable to reproduce Unable to identify cause and attempts to reproduce have been unsuccessful. Occurrence will be added and issue re-opened to New status.
Closed Rejected Issue is not being fixed e.g. only affected older operating systems Occurrence will be added only. Issue remains in Rejected status.

Scroll through the list of Connectors to Incoming Webhook, and choose Add.

Enter a name for the webhook, upload an image to associate with data from the webhook, and choose Create.

Copy the webhook to the clipboard and save it. You’ll need the webhook URL for sending information to Microsoft Teams.
Choose Done.

You should see a message in the Microsoft Teams channel that a new integration has been added.

Configure Webhook URL in cmercury

Click on the app and then select Crash in the left hand menu to open the Crash Dashboard for that app. Click on the settings cog next to Microsoft Teams in Integrations on the right and paste in the Webhook URL copied from Microsoft Teams earlier.

Click “Configure” and you should see that Microsoft Teams integration is now configured.

Now, when a new issue occurs, your team will be immediately notified in Microsoft Teams.

Trello

Once you have been notified of a new crash, you can create a card in Trello to track the fix.

Click on the app, expand Crash in the left hand menu and select “Issues”. Click on the new issue and from the context menu for an issue, select “Create Trello Card”

This will open a new browser window prompting you to login to Trello if not already logged in.

Enter an optional description for the card and then select the board where you want to add the card.

Finally, select the column where the list is to be added.

A card will be created in Trello with the title of the issue from cmercury.

You can either click on the link to the card to see it in Trello or, when viewing the issue in cmercury, you can click “View on Trello”.

The card in Trello will contain a link back to the issue in cmercury, so your team can access all of the stack traces and logs they need to implement a fix.

Don’t forget to update the status of the issue in cmercury when a fix for the crash is in progress and again once you are satisfied that the crash has indeed been fixed.

Next time there is a new crash of this app and you want to create a card in Trello, cmercury will remember the board and list you selected previously, meaning you only need to give the card an optional description. However, you can easily select a different list or board if required.

Jira

Once you have been notified of a new crash, you can create an issue in Jira to track the fix.

Please note that this integration is for Atlassian Cloud Jira only and not self-hosted Jira.

Configure Jira Credentials

Click on the app and then select Crash in the left hand menu to open the Crash Dashboard for that app. Click on the settings cog next to Jira in Integrations on the right.

Enter the URL of the project in which you want issues created. This is normally of the form:

https://<INSTANCE>.atlassian.net/projects/<KEY>

Then enter the username and password of a user that can create issues. These credentials will be encrypted and cmercury will never reveal your password.

Click “Configure” and you should see that Jira integration is now configured.

Create issue in Jira

When you want to create an issue in Jira, expand Crash in the left hand menu and select “Issues”. Click on the new issue and from the context menu for an issue, select “Create JIRA Issue”

Once the issue has been created, you can click “View in JIRA”.

The issue in Jira will contain a link back to the issue in cmercury, so your team can access all of the stack traces and logs they need to implement a fix.

Don’t forget to update the status of the issue in cmercury when a fix for the crash is in progress and again once you are satisfied that the crash has indeed been fixed.

App Store Optimization

Overview

65% of all app downloads come from searches in the app stores. This is why getting and keeping the listing on the app store right is so important. With the easy-to-use App Store Optimization feature in cmercury you can do just that by:

  • Tracking where an app ranks in search results versus competitive apps
  • Viewing volume, contention and ranking over time for different search terms
  • Comparing the App Store listing and Google Play Store listing side-by-side
  • Comparing the listing to that of competitive apps and top apps in category
  • Viewing the most recent and also most helpful reviews

App Store Optimization can be setup in minutes and used both to refine the listing of existing apps and to start preparing the listing for the launch of new apps by tracking competitive apps’ listings and how they rank for different search terms.

The following short video explains how App Store Optimization from cmercury can help your app grow and thrive by:

  • Getting launch ready
  • Winning more business
  • Selling after-launch care services

Video Link

Enable ASO

Configuration

To configure the App Store Optimization feature, you need to:

• (Optionally) Find the app in the App Store and/or Play Store
• Enter the terms that you think prospective users will search for
• Identify the competitive apps that you want to be measured against

Note that you can use ASO before you submit the app to the stores to track competitive apps’ listings and how they rank for different search terms so that you get the listing right when it comes time to launch! In this case, just skip the first step in the configuration wizard below.

Find your app

If the app has not been submitted to the stores, but you want to use ASO to track competitive apps’ listings and how they rank for different search terms, skip this step and go to enter search terms.

If the app is in the stores, then you need to find your app in the App Store and Play Store so that cmercury can track how it ranks for different search terms. First of all select the country you wish to search (defaults to United States) from the drop-down.

Enter a search term and click “SEARCH”

From the results displayed, select the app in the App Store and the Play Store.

If the app is not listed, please check that it is available in the country you have selected and then refine your search term and search again. If it is listed in one store, but not another, select the app in the store that it is listed, refine your search term and search again.

Once you have selected the app in both stores, click “Next” to start entering the terms that you think prospective users will search for.

Enter search terms

cmercury lets you enter upto five terms that you think prospective users will search for so you can see how the app (if it is already available in the store) and competitive apps rank for these search terms. Enter a search term, which can be more than one word, and click “Add”

Once you have entered your search terms, click “Next” to identify competitive apps.

Identify competitive apps

cmercury lets you identify upto three apps that you can compare listings against and track search rankings over time for different terms. You can search for competitive apps yourself or click “Search based on keywords” to use the search terms you entered above to search for apps. Note that when searching, your app will hopefully be shown in the search results if your listing is optimized for those terms.

From the results displayed, select upto three competitive apps in the App Store and three competitive apps in the Play Store. Note you do not need to select the same apps in each store.

Enter different search terms as required to find all of the competitive apps. When done, click ‘Next’ to complete the setup and start your 30-day free trial of the App Store Optimization feature in cmercury.

ASO dashboard

Once configured, the ASO Dashboard lets you compare the App Store and Play Store listings side-by-side. Click the down arrow to expand the description and release notes for one or both stores.

In the left hand menu, under ASO, you can select either “App Store” or “Play Store” to view more details about how your app is ranking in the Apple App Store or Google Play Store respectively.