diff --git a/basics/acquisition.md b/basics/acquisition.md index 6547126..2e61e7e 100644 --- a/basics/acquisition.md +++ b/basics/acquisition.md @@ -19,6 +19,10 @@ User acquisition represents the entry point of your app's growth funnel – how With TelemetryDeck's Acquisition dashboard, these insights are automatically collected and visualized with no additional code required beyond updating to the latest SDK version. +{% noteinfo "How TelemetryDeck Detects New Users" %} +New users are detected by the `TelemetryDeck.Acquisition.newInstallDetected` signal that is automatically sent on first app launch. +{% endnoteinfo %} + ## User growth trends **Questions you can answer:** diff --git a/basics/activation.md b/basics/activation.md new file mode 100644 index 0000000..0485740 --- /dev/null +++ b/basics/activation.md @@ -0,0 +1,97 @@ +--- +title: Activation Analytics +tags: + - setup + - basics + - pirate-metrics + - activation +basics: true +description: Learn how to interpret and act on TelemetryDeck's activation metrics to optimize your app's first-time user experience. +lead: Activation is the second stage of the Pirate Metrics framework, focusing on when users experience your app's core value for the first time. TelemetryDeck automatically tracks these patterns to help you optimize the crucial first sessions that turn new users into engaged users. +searchEngineTitle: 14 Questions to Ask to Improve User Activation | TelemetryDeck +searchEngineDescription: Learn how to interpret user activation data for your mobile app with TelemetryDeck's automatic activation analytics. +order: 21 +--- + +## What is User Activation? + +User activation represents the critical moment when users first experience your app's core value – the "aha moment" that transforms them from curious installers into engaged users. These metrics help you understand how well your Onboarding works, identify friction points, and optimize the first-time experience. + +With TelemetryDeck's Activation dashboard, these insights are automatically collected and visualized with no additional code required beyond updating to SwiftSDK 2.8.0 / KotlinSDK 6.0.0 or later. + +{% noteinfo "How TelemetryDeck Detects Activated Users" %} +Activated users are those with at least 5 minutes accumulated total usage time within their first 5 sessions. +{% endnoteinfo %} + +## Activated user growth trends + +**Questions you can answer:** +- How many users are experiencing my app's core value? +- Are my activation rates improving over time? +- How effective is my Onboarding experience? +- What are the immediate activation patterns in the last 24 hours? + +![Hourly, Daily, Weekly, and Monthly Activated Users](/docs/images/activation-activated-users.png) + +**How to interpret the charts:** +- **Hourly (last 24h)**: Shows recent activation activity and immediate trends – useful for spotting issues or validating recent changes +- **Daily patterns**: Consistent upward trend indicates your Onboarding is working well; sudden spikes may correlate with improvements or campaigns +- **Weekly/Monthly trends**: Reveal longer-term activation health and seasonal patterns +- **Declining trends**: May indicate Onboarding friction, confusing first experiences, or performance issues + +**How to read your data:** In this example dashboard, the monthly chart shows activation building from earlier months to peak around March-April (~50+ users), demonstrating successful activation strategies reaching strong performance levels. The weekly data shows more stable patterns (12-15 user range) compared to daily fluctuations (1-8 users with occasional spikes), which suggests normal variation rather than systemic issues. Use the hourly chart to immediately validate Onboarding changes – if activation drops after deploying improvements, investigate quickly. + +## Activation time patterns + +**Questions you can answer:** +- When during the day do users typically get activated? +- Which days of the week see the most successful first experiences? +- Do weekdays or weekends provide better conditions for user activation? +- Are recent activation patterns consistent with long-term trends? + +![Activation Time Patterns](/docs/images/activation-by-time.png) + +**How to interpret the charts:** +- **Hour of day patterns**: Show when users have time to properly explore your app (user-local timezone) +- **Day patterns (past 4 weeks)**: Reveal specific days with exceptional activation performance +- **Weekend vs. weekday balance**: Indicates whether activation requires focused time or fits into busy schedules +- **Recent trends**: Help identify if timing patterns are changing over time + +**How to read your data:** In this example, the Hour of Day chart shows peak activations around 12-1 PM and 5-6 PM, which would suggest users activate during lunch breaks and after work hours when they have focused time to explore the app. The Day of Week chart shows Friday with the strongest activation performance (34 users) and Sunday with the lowest (21 users), indicating a weekday preference for activation. If you see similar patterns in your data, it would suggest users are more likely to experience your app's core value during structured time periods. You could then time your Onboarding prompts and feature introductions for weekday lunch periods and early evenings when users are most engaged. + +## Activation by device & platform + +**Questions you can answer:** +- Which devices provide the best activation experience? +- Should I optimize my Onboarding for specific hardware or screen sizes? +- Are there platform-specific activation barriers? + +![Activated Users by Device Type](/docs/images/activation-device-distribution.png) + +**How to interpret the chart:** +- **Top-performing devices**: These provide the best activation experience – understand why +- **Low activation devices**: May have UI issues, performance problems, or usability challenges +- **Platform differences**: iOS vs. Android vs. other platforms may have different activation patterns + +**How to read your data:** In this example, iOS users represent 60% of activated users while macOS represents 40%. Among individual devices, iPhone 15 Pro Max leads at 8.57%, with several models each representing around 5.71% of activations. When you see relatively even distribution across device types like this, it suggests the Onboarding experience works consistently well across platforms. A strong secondary platform presence (like the 40% macOS here) would indicate successful cross-platform activation. If you see similar patterns, focus your testing efforts on the leading device models while maintaining cross-platform activation quality. + +## Activation by geography & language + +**Questions you can answer:** +- Where are users most successfully experiencing my app's value? +- What languages correlate with higher activation rates? +- Which markets provide the strongest foundation for growth? + +![Activated Users by Country and Language](/docs/images/activation-geographic-distribution.png) + +**How to interpret the charts:** +- **Strong activation regions**: Countries where users consistently experience your app's value +- **Emerging markets**: Regions with growing activation that may warrant localization investment +- **Language correlation**: Languages that correlate with successful activation experiences + +**How to read your data:** In this example dashboard, Germany (37.14%) shows as the strongest activation market, followed by Italy (14.29%) and the United States (8.57%). The language distribution shows German (48.57%) and English (28.57%) users with the strongest activation patterns, plus Italian (17.14%) showing significant engagement. When you see patterns like this in your own data, it would suggest your Onboarding experience works particularly well for certain language groups. You could then prioritize localization efforts for your top-performing regions to maximize activation in those markets. + + +## Taking action on activation insights + +The key to improving activation lies in asking the right questions and forming creative hypotheses about your data patterns. Look beyond the obvious metrics – combine insights across time, geography, and device patterns to uncover unique opportunities for your app. Remember that successful activation is the foundation for retention: users who experience your app's core value in their first sessions are much more likely to become long-term, engaged users who drive sustainable growth. diff --git a/basics/index.md b/basics/index.md index e4af9a2..fe69f3d 100644 --- a/basics/index.md +++ b/basics/index.md @@ -38,13 +38,13 @@ Each tab focuses on a different stage of the user journey: **Acquisition** tracks how users find and install your app, with metrics for new user counts, device distribution, geographic insights, and typical discovery patterns. -**Activation** (Coming Soon) monitors initial engagement with metrics like active user counts, session length distribution, and usage patterns by time of day and day of week. +**Activation** monitors when users experience your app's core value for the first time, with metrics for activated user counts, session patterns, and first-time user experience optimization. -**Retention** (Coming Soon) measures how effectively your app keeps users coming back, tracking distinct days used, engaged user metrics, and power user identification. +**Retention** (🚧 In Progress) measures how effectively your app keeps users coming back, with metrics for distinct days used, session frequency, engaged user identification, and long-term usage patterns. -**Referral** (Coming Soon) helps understand how users share your app with others. +**Referral** (⏳ Coming Soon) helps understand how users share your app with others. -**Revenue** (Coming Soon) tracks your app's financial performance metrics. +**Revenue** (⏳ Coming Soon) tracks your app's financial performance metrics.
@@ -58,12 +58,32 @@ Each tab focuses on a different stage of the user journey:

Learn how to interpret and act on acquisition metrics to optimize how users discover your app.

+
+
+
+

+ + Activation Analytics +

+

Learn how to interpret and act on activation metrics to optimize your app's first-time user experience.

+
+
+
+
+
+

+ + Retention Analytics +

+

Learn how to interpret and act on retention metrics to keep users engaged long-term.

+
+

- Understanding Pirate Metrics Framework + Understanding Pirate Metrics

Learn about the AARRR framework that organizes analytics by acquisition, activation, retention, referral, and revenue.

diff --git a/basics/retention.md b/basics/retention.md new file mode 100644 index 0000000..7e83c31 --- /dev/null +++ b/basics/retention.md @@ -0,0 +1,97 @@ +--- +title: Retention Analytics +tags: + - setup + - basics + - pirate-metrics + - retention +basics: true +description: Learn how to interpret and act on TelemetryDeck's retention metrics to keep users engaged long-term. +lead: Retention is the third stage of the Pirate Metrics framework, focusing on how effectively your app keeps users coming back over time. TelemetryDeck automatically tracks these patterns to help you optimize long-term user engagement and identify your most valuable users. +searchEngineTitle: 10 Best User Retention Metrics | TelemetryDeck +searchEngineDescription: Learn how to interpret user retention data for your mobile app with TelemetryDeck's automatic retention analytics. +order: 22 +--- + +## What is User Retention? + +User retention measures how effectively your app keeps users coming back after their initial experience. These metrics help you understand user loyalty, reduce churn rate, identify engagement patterns, and spot opportunities to strengthen long-term relationships with your user base – ultimately increasing customer lifetime value (LTV). + +With TelemetryDeck's Retention dashboard, these insights focus on users who can be considered "returning users" (those with more than 5 sessions) and are automatically collected with no additional code required beyond updating to SwiftSDK 2.8.0 / KotlinSDK 6.0.0 or later. + +{% noteinfo "How TelemetryDeck Detects Returning Users" %} +Returning users are those who have used your app for more than 5 sessions. +{% endnoteinfo %} + +## Returning user growth trends + +**Questions you can answer:** +- How many of my users are becoming regular, returning users? +- Are my retention rates improving over time? +- What are the immediate retention patterns in the last 24 hours? +- How do retention trends compare across different time periods? + +![Hourly, Daily, Weekly, and Monthly Returning Users](/docs/images/retention-returning-users.png) + +**How to interpret the charts:** +- **Hourly (last 24h)**: Shows recent returning user activity – useful for immediate validation of retention initiatives +- **Daily patterns**: Consistent levels indicate stable user engagement; growth suggests improving retention strategies +- **Weekly/Monthly trends**: Reveal long-term retention health and seasonal engagement patterns +- **Declining trends**: May indicate rising churn rate due to user experience issues, feature problems, or competitive pressures + +**How to read your data:** In this example dashboard, the monthly chart shows excellent retention growth from March (~8 users) building steadily through the months to reach a strong July peak (~57 users), indicating highly successful retention strategies building momentum over time. The weekly view shows more gradual growth from ~8 to ~35 users over the past 3 months, while daily retention fluctuates between 3-15 users with occasional spikes. Use the daily fluctuations to validate immediate retention initiatives rather than waiting for weekly trends to develop. + +## Retention time patterns + +**Questions you can answer:** +- When do returning users typically engage with my app during the day? +- Which days of the week show the strongest user loyalty? +- Do returning users prefer weekdays or weekends for app usage? +- Are retention patterns changing over recent weeks? + +![Retention Time Patterns](/docs/images/retention-by-time.png) + +**How to interpret the charts:** +- **Hour of day patterns**: Show when returning users are most active (user-local timezone) +- **Day of week distribution**: Reveals which days drive the strongest retention engagement +- **Day patterns (past 4 weeks)**: Identify specific days with exceptional returning user activity +- **Weekend vs. weekday balance**: Indicates whether your app fits into work routines or leisure time + +**How to read your data:** In this example, the Hour of Day chart shows returning users are most active during midday hours (12-3 PM) with peak activity around 2 PM, suggesting users engage with the app during lunch breaks and afternoon periods. The Day of Week chart reveals Wednesday shows the strongest retention (~55 users), followed by Tuesday (~53) and Monday (~50), while Thursday shows the lowest (~40). Friday through Sunday maintain consistent moderate levels (~45 each). When you see patterns like this in your data, it would indicate your app fits well into midweek routines. You could then schedule feature updates and important communications for Wednesday when user engagement peaks. + +## Retention by device & platform + +**Questions you can answer:** +- Which devices retain users most effectively? +- Are there platform-specific retention challenges? +- Should I prioritize retention improvements for specific hardware? + +![Returning Users by Device Type](/docs/images/retention-device-distribution.png) + +**How to interpret the charts:** +- **Top-retention devices**: These provide the best long-term user experience +- **Poor retention devices**: May have performance issues, UI problems, or technical barriers +- **Platform differences**: iOS vs. macOS vs. other platforms may show different retention strengths + +**How to read your data:** In this example, iOS represents 60% of returning users while macOS accounts for 40%. Among individual devices, several models each contribute about 10% of returning users (iPhone 12 mini, iPad 9th generation, various MacBook Air and MacBook Pro models). When you see relatively even distribution across device types like this, it suggests your app provides consistent long-term value across different platforms and device generations. The strong macOS presence (40%) would indicate successful cross-platform retention and higher repeat purchase rate (RPR) for users who engage across multiple devices. If you see similar patterns, focus on maintaining this consistency rather than optimizing for specific hardware configurations. + +## Retention by geography & language + +**Questions you can answer:** +- Which regions show the strongest user loyalty? +- What languages correlate with higher long-term engagement? +- Are there cultural or regional patterns in user retention? + +![Returning Users by Country and Language](/docs/images/retention-geographic-distribution.png) + +**How to interpret the charts:** +- **High-retention regions**: Countries where users consistently return to your app +- **Growing markets**: Regions showing improving retention that warrant additional investment +- **Language loyalty patterns**: Languages that correlate with strong long-term engagement + +**How to read your data:** In this example dashboard, Germany dominates at 50% of returning users, with several other countries each representing about 10% (Italy, India, Spain, Canada, Afghanistan). The language distribution shows English (40%) and German (30%) as the primary languages, with Turkish (10%) as a notable third language. When you see such strong geographic concentration in your own data (like Germany's 50% here), it suggests that users in this region find exceptional long-term value in your app. You could then study what works particularly well for your top-retention market and apply those insights to improve retention in other regions. + + +## Taking action on retention insights + +The key to improving retention lies in asking the right questions and forming creative hypotheses about your data patterns. Look beyond the obvious metrics – combine insights across time, geography, and device patterns to uncover unique opportunities for keeping users engaged and maximizing customer lifetime value (LTV). Remember that retention is where sustainable app growth happens: users who return regularly generate the most value, provide the best feedback, and become your strongest advocates for organic growth. diff --git a/images/activation-activated-users.png b/images/activation-activated-users.png new file mode 100644 index 0000000..f34870a Binary files /dev/null and b/images/activation-activated-users.png differ diff --git a/images/activation-by-time.png b/images/activation-by-time.png new file mode 100644 index 0000000..a12eb3b Binary files /dev/null and b/images/activation-by-time.png differ diff --git a/images/activation-device-distribution.png b/images/activation-device-distribution.png new file mode 100644 index 0000000..729cc92 Binary files /dev/null and b/images/activation-device-distribution.png differ diff --git a/images/activation-geographic-distribution.png b/images/activation-geographic-distribution.png new file mode 100644 index 0000000..4c86579 Binary files /dev/null and b/images/activation-geographic-distribution.png differ diff --git a/images/retention-by-time.png b/images/retention-by-time.png new file mode 100644 index 0000000..b7a3860 Binary files /dev/null and b/images/retention-by-time.png differ diff --git a/images/retention-device-distribution.png b/images/retention-device-distribution.png new file mode 100644 index 0000000..46ad520 Binary files /dev/null and b/images/retention-device-distribution.png differ diff --git a/images/retention-geographic-distribution.png b/images/retention-geographic-distribution.png new file mode 100644 index 0000000..c48f45e Binary files /dev/null and b/images/retention-geographic-distribution.png differ diff --git a/images/retention-returning-users.png b/images/retention-returning-users.png new file mode 100644 index 0000000..615a93d Binary files /dev/null and b/images/retention-returning-users.png differ diff --git a/ingest/default-parameters.md b/ingest/default-parameters.md index 9e7656b..724a0d5 100644 --- a/ingest/default-parameters.md +++ b/ingest/default-parameters.md @@ -164,7 +164,7 @@ Navigation analytics signals have these parameters, which can be included in any - `TelemetryDeck.Calendar.isWeekend`: `true` if the day of the week is Saturday or Sunday, `false` otherwise. - `TelemetryDeck.Calendar.monthOfYear`: The number-of-the-month (1..12) component of the date. - `TelemetryDeck.Calendar.quarterOfYear`: The the quarter-of-year (1..4). For API 26 and earlier, it's the number of the month divided by 3. -- `TelemetryDeck.Calendar.hourOfDay`: The hour-of-day (0..23) time component of this time value. +- `TelemetryDeck.Calendar.hourOfDay`: The hour-of-day (1..24) time component. 1 = 00:00-00:59, 10 = 09:00-09:59, 24 = 23:00-23:59. - `TelemetryDeck.Acquisition.firstSessionDate`: The date of the first session e.g. 2025-02-22 - `TelemetryDeck.Retention.averageSessionSeconds`: The average session duration in seconds. - `TelemetryDeck.Retention.distinctDaysUsed`: The number of distinct dates on which the app was used.