Customer Lifecycle Analytics for Your App
This guide covers how to instrument your Ring Appstore app to track the full customer lifecycle—from account linking through engagement and subscription conversion. It includes recommended events, metrics, and dashboard patterns based on real implementation experience.
Without visibility into your customer journey, you can't identify where users drop off, which features drive retention, or what's blocking conversions. Structured tracking lets you make data-driven decisions about your app's UX, pricing, and feature development.
On this page
- Account linking funnel
- Subscription tracking
- Feature engagement
- Webhook health
- Error tracking
- Recommended dashboards
Account linking funnel
Track each step of the account linking flow to identify where customers drop off.
To reduce friction, passwordless account linking has shown positive results in reducing drop-off during the linking flow. For implementation details, see Your App Design Guide for Ring Customer Experiences.
Recommended events
The following table shows the events to log at each step of the account linking flow.
| Step | Where to log | What it tells you |
|---|---|---|
token_exchange |
Your OAuth token endpoint, when Ring sends the access token | Total users who initiated linking from Ring |
page_loaded |
Client-side, when your signup or login page renders | Users who actually opened your page (gap from token_exchange = Ring-side drop-off) |
auth_attempt |
Client-side, on form submit | Users who tried to sign up or sign in |
auth_failed |
Client-side, on error response (include the error in detail) |
Where users get stuck |
link_complete |
Server-side, after successful Ring API nonce verification | Users who fully completed account linking |
What to look for
token_exchange→page_loadedgap: Ring-side drop-off before users reach your page. Users are browsing your app detail page and deciding whether to proceed. This is outside your control.page_loaded→link_completegap: Your signup flow friction. With passwordless auto-linking, this should be near zero percent.
Include a version tag (v) in events so you can measure before-and-after impact when you deploy UX changes.
Example: account linking funnel
The following diagram — "Example: before vs after deploying passwordless auto-linking" — compares account linking conversion before and after deploying passwordless auto-linking. The left panel shows the traditional email/password flow, where customers drop off at both the Ring-side decision point and your signup form. The right panel shows the passwordless flow, where the only drop-off is Ring-side — customers who reach your page complete linking automatically, with no form required. The conversion stats at the bottom show the practical impact: a jump from 60% to 100% page-to-complete conversion.
Subscription tracking
Track the customer lifecycle from account creation through trial to paid conversion. Understanding where users drop off in this journey tells you whether to invest in onboarding, feature depth, or pricing. The key signal is engagement before churn—it separates onboarding problems from value problems.
Recommended events
The following table shows the events to log across the subscription lifecycle.
| Event | When | Detail |
|---|---|---|
trial_started |
Account linking complete | Trial start date, expiry date |
trial_active |
Daily check-in | Days remaining, feature usage |
trial_expired |
Trial period ends | Whether user engaged (had detections, visited dashboard) |
subscription_converted |
User pays | Plan type, trial duration before conversion |
subscription_churned |
User cancels or doesn't renew | Days as subscriber, last active date |
app_removed |
Ring sends app_integration_removed webhook |
Time since linking, feature usage |
Key metrics to compute
- Trial-to-paid conversion rate: What percentage of free trial users become paying subscribers.
- Time to first value: How quickly users experience the core feature (for example, first bird detection). Users who never see value churn.
- Engagement before churn: Did churned users ever use the app? Zero engagement indicates an onboarding problem; high engagement indicates a pricing or value problem.
Example: subscription tracking
The following diagram — "What happens after account linking — tracking 120 users who completed linking" — traces what happened to 120 users after they completed account linking. The top section shows the lifecycle pipeline — how many reached each stage from trial through paid conversion. The bottom section breaks down churn by engagement level, revealing whether customers who removed the app had ever used it at all. The color coding makes the pattern clear: the less a customer engaged, the more likely they were to churn, and the remedies are different at each level.
Feature engagement
Track which features customers actually use to inform development priorities and identify what drives retention.
Recommended events
The following table shows the events to log for feature engagement.
| Event | What it tells you | How to use the data |
|---|---|---|
dashboard_visit |
How often users check in | Define "active" versus "dormant" cohorts. Users visiting less than once per week may need re-engagement nudges. |
feature_used (with feature name) |
Which features drive engagement | Compare usage across features to identify what to invest in versus deprioritize. Features with high usage and high retention correlation are your competitive advantage. |
notification_opened |
Whether push or email notifications bring users back | Measure re-engagement rate. If open rates drop, reduce frequency before users disable notifications entirely. |
share_action |
Social or viral potential | Track as a leading indicator of organic growth. High share rates suggest your content is compelling enough to drive word-of-mouth. |
Tips for useful engagement tracking
- Define "active user" explicitly. Is it a dashboard visit? Any event? A core feature use? Pick one definition and stick with it so your metrics are consistent over time.
- Compare by cohort. Group users by signup week. This separates product changes from seasonal patterns — if the week 12 cohort retains better than the week 10 cohort, your recent changes are working.
- Don't over-instrument. Not every action is useful. Focus on actions that correlate with retention (core feature usage, return visits) rather than vanity metrics (page views, button hovers).
- Tie engagement to subscription outcomes. The most valuable insight is: "Users who do X within their first three days convert at twice the rate." Find your app's version of that signal.
Webhook health
Ring sends webhooks for motion events, app integration changes, and device updates. Your webhook endpoint must meet two requirements:
- Return a 200 status code for every successfully received webhook. Ring treats any non-2xx response as a delivery failure and will retry the request. Persistent failures may result in Ring disabling webhook delivery to your endpoint.
- Respond within five seconds. If your endpoint takes longer than five seconds to respond, Ring treats it as a timeout. Don't perform heavy processing (video downloads, AI inference, database writes) synchronously in the webhook handler. Instead, acknowledge the webhook immediately with a 200 response and process the payload asynchronously via a queue (for example, SQS or a background worker).
Track response codes and timing to ensure you're meeting these requirements consistently.
What to log
The following code example shows the recommended webhook log format.
{
"type": "WEBHOOK_LOG",
"event_type": "motion_detected",
"subtype": "other_motion",
"account_id": "<last 20 chars>",
"device_id": "<last 20 chars>",
"response_time_ms": 145,
"status": 200
}
Key metrics
The following table shows the target values and recommended actions for webhook health metrics.
| Metric | Target | Action if missed |
|---|---|---|
| Success rate (2xx responses) | 100% | Investigate 5xx errors — Lambda timeouts, DynamoDB throttling |
| Response time | Under three seconds | Ring may retry or drop webhooks that take too long |
| Duplicate detection | Log event IDs | Ring may send the same event multiple times — deduplicate by event ID |
Alert on
- 5xx rate exceeding one percent
- Response time exceeding five seconds
- Sudden drop in webhook volume, which may indicate a Ring-side issue or token expiry
Error tracking
Log all customer-facing errors with enough context to debug and resolve quickly.
Recommended format
The following code example shows the recommended error log format.
{
"type": "ERROR_LOG",
"endpoint": "/auth/verify-code",
"error": "Code expired",
"user_email_masked": "joh***@gmail.com",
"timestamp": "<ISO 8601>"
}
What to track
- Login failures (wrong code, expired code, user not found)
- Account linking failures (nonce mismatch, token expired)
- API errors returned to customers (4xx and 5xx)
- Ring API call failures (token refresh failures, rate limits)
Recommended dashboards
Set up automated dashboards or alerts for the following metrics.
| Dashboard | What to include |
|---|---|
| Daily account linking conversion | Initiated versus completed, with version comparison |
| Webhook health | Success rate, response time, volume over time |
| Trial status | Active trials, expiring soon, converted, churned |
| Error rate | Customer-facing errors per hour, grouped by type |
| Engagement | Daily active users, feature usage trends |
