Mobile app docs updates (#2026)

# What this PR does

This is the first of many mobile app doc tweaks.

Note that right now the docs are very much out of date.
To make this a smooth process, I recommend to merge if it looks "good
enough", don't sweat details at this time. We can make further
refinements later.
If @imtoori approves, this PR may be merged as is, and i'll make new
ones in the future, or i will just keep pushing more and more tweaks
over the next few business days

## Which issue(s) this PR fixes

## Checklist

- [ ] Unit, integration, and e2e (if applicable) tests updated
- [x] Documentation added (or `pr:no public docs` PR label added if not
required)
- [x] `CHANGELOG.md` updated (or `pr:no changelog` PR label added if not
required)

---------

Co-authored-by: Salvatore Giordano <salvatoregiordanoo@gmail.com>
Co-authored-by: Matvey Kukuy <Matvey-Kuk@users.noreply.github.com>
Co-authored-by: Matvey Kukuy <motakuk@gmail.com>

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add models and framework to use different services (Phone, SMS, Verify) in Twilio depending on
 the destination country code by @mderynck ([#1976](https://github.com/grafana/oncall/pull/1976))
 - Prometheus exporter backend for alert groups related metrics
+- Much expanded/improved docs for mobile app ([2026](https://github.com/grafana/oncall/pull/2026>))
 - Enable by-day selection when defining monthly and hourly rotations ([2037](https://github.com/grafana/oncall/pull/2037))
 
 ### Fixed

docs/README.md

@@ -8,3 +8,7 @@ Run `make docs`. This launches a preview of the website with the current grafana
 `http://localhost:3002/docs/oncall/latest/` which will refresh automatically when changes are made to
 content in the `sources` directory.
 Make sure Docker is running.
+
+## Image support
+
+See [the documentation in writers toolkit about how to store images](https://grafana.com/docs/writers-toolkit/writing-guide/image-guidelines/#where-to-store-media-assets)

docs/sources/mobile-app/_index.md

@@ -2,6 +2,7 @@
 title: Mobile App
 aliases:
   - /docs/oncall/latest/mobile-app/
+canonical: https://grafana.com/docs/oncall/latest/mobile-app/
 keywords:
   - Mobile App
   - oncall
@@ -12,24 +13,18 @@ weight: 1100
 
 # Grafana OnCall Mobile App
 
->**Note**: This application is currently in beta and has limited functionality.
-
 The Grafana OnCall mobile app allows teams to monitor and respond to critical system events from anywhere.
 On-call engineers can start exploring the benefits of the Grafana OnCall mobile app, with real-time alerts, on-call notifications, and a growing feature set.
 
 ## About Grafana OnCall mobile app
 
-The current version of the mobile app includes limited functionality and serves primarily as a notification method.
-The mobile app is in development, and some features are not yet available.
-
-Stay tuned, we're working on it!
-
 Grafana OnCall mobile app key features:
 
-- Override Do Not Disturb on your device to ensure delivery of critical alerts
+- Override Do Not Disturb on your device to ensure delivery of important alerts
 - Receive push notifications according to your personal notification settings
-- View alert details from your mobile device
+- Viewing, filtering and responding to Alert Groups (acknowledge, resolve, silence, etc).
 - Login with a quick and secure QR code authorization
+- View your on-call status and information about current and upcoming shift
 
 The OnCall mobile app allows users to receive push notifications as part of their notification policy.
 Push notifications are one of the many notification options in Grafana OnCall.
@@ -37,65 +32,4 @@ Push notifications are one of the many notification options in Grafana OnCall.
 Consider using multiple notification methods, such as mobile app and phone/SMS,
 to remain available in case of degraded internet or phone network connectivity.
 
-## Before you begin
+{{< section >}}
-
-The Grafana OnCall mobile app is intended to be used as an extension of your Grafana OnCall instance.
-Grafana OnCall is available for Grafana Cloud and Grafana open source users.
-
-- You must have a Grafana OnCall account to use this application
-- Download Grafana OnCall mobile app
-
-Mobile app download:
-
-- [Google Play Store](https://play.google.com/store/apps/details?id=com.grafana.oncall.prod)
-- [Apple App Store](https://apps.apple.com/us/app/grafana-oncall-preview/id1669759048)
-
-## Connect your Grafana OnCall account
-
-The OnCall mobile app uses a QR code authentication to connect to your Grafana OnCall instance.
-You can associate one Grafana OnCall user with your OnCall mobile app.
-
-To connect your account in the mobile app:
-
-1. Open the Grafana OnCall mobile app and click **Sign in**
-2. Follow the instructions in the app to complete QR code authentication
-3. Once the scan is successful, your mobile app is connected to OnCall
-
-### Where can I find my QR code?
-
-To access your QR code:
-
-1. Open Grafana OnCall from your desktop
-1. Navigate to the **Users** tab, then click **View my profile**
-1. Click **Mobile app connection** in your profile
-
->**Note**: The QR code will timeout for security purposes - Screenshots of the QR code are unlikely to work for authentication.
-
-### Connect to your open source Grafana OnCall account
-
-Grafana OnCall OSS relies on Grafana Cloud as on relay for push notifications.
-You must first connect your Grafana OnCall OSS to Grafana Cloud for the mobile app to work.
-
-To connect to Grafana Cloud, refer to the Cloud page in your OSS Grafana OnCall instance.
-
-For Grafana OnCall OSS, the QR code includes an authentication token along with a backend URL.
-Your Grafana OnCall OSS instance should be reachable from the same network as your mobile device, preferably from the internet.
-
-## Mobile app push notifications
-
-There are two push notification options for the mobile app:
-
-- **Mobile push** - Sends a typical push notification to your mobile device according to your device and app notification settings.
-Intended for all types of alerts.
-- **Mobile push important** - Sends a privileged push notification that can bypass Do Not Disturb on your device.
-Intended for critical alerts. Device-specific settings may impact the functionality of these notifications.
-
->**Note**: Android users may need to review their device settings to ensure the Grafana OnCall mobile app is authorized to bypass Do Not Disturb.
-> In your device settings, allow the Android Critical Message Channel notification channel to Override Do Not Disturb.
-
-### Add mobile app to notification preferences
-
-To receive push notifications from the Grafana OnCall mobile app, you must add them to your notification policy steps.
-
-1. From Grafana OnCall, navigate to the **Users** tab and click **View my profile**
-1. In your **User Info** tab, update your Default and Important notification policies to include Mobile push notifications.

docs/sources/mobile-app/alert-groups-feed/index.md

@@ -0,0 +1,25 @@
+---
+canonical: https://grafana.com/docs/oncall/latest/mobile-app/alert-groups-feed/
+keywords:
+  - Mobile App
+  - oncall
+  - notification
+  - push notification
+  - alert groups
+title: Alert Groups feed
+weight: 200
+---
+
+# Alert Groups feed
+
+On the **Feed** page, you can view Alert groups, under two tabs:
+
+- **Mine** shows Alert Groups that involve you in one way or another. E.g. because a notification went to you about it, or you resolved it.
+- **All** shows all Alert Groups, including ones that may not be relevant to you.
+
+You can filter by status via the **filter** button on the top right.  We are working on an expansion for this filter, to filter by team, integration name, and more.
+
+Tap on any Alert Group to go to the detailed view.  This page also provides links for opening in slack and sharing the link to this alert group.
+
+<img src="/static/img/oncall/mobile-app-alertgroups.png" width="300px">
+<img src="/static/img/oncall/mobile-app-alertgroup.png" width="300px">

docs/sources/mobile-app/installation-and-setup/index.md

@@ -0,0 +1,57 @@
+---
+canonical: https://grafana.com/docs/oncall/latest/mobile-app/installation-and-setup/
+keywords:
+  - Mobile App
+  - oncall
+  - notification
+  - push notification
+title: Installation and setup
+weight: 100
+---
+
+# Installation and setup
+
+The Grafana OnCall mobile app is an extension of your Grafana OnCall instance.
+Grafana OnCall is available for Grafana Cloud and Grafana open source users.
+You must have a Grafana OnCall account to use this application.
+
+## Installation of the Grafana Oncall Mobile app
+
+Mobile app download:
+
+- [Google Play Store](https://play.google.com/store/apps/details?id=com.grafana.oncall.prod)
+- [Apple App Store](https://apps.apple.com/us/app/grafana-oncall-preview/id1669759048)
+
+## Connect your Grafana OnCall account
+
+The OnCall mobile app uses a QR code authentication to connect to your Grafana OnCall instance.
+You can associate one Grafana OnCall user with your OnCall mobile app.
+
+To connect your account in the mobile app:
+
+1. Open the Grafana OnCall mobile app and tap **Sign in**
+2. Follow the instructions in the app to complete QR code authentication
+3. Once the scan is successful, your mobile app is connected to OnCall
+
+<img src="/static/img/oncall/mobile-app-first-screen.png" width="300px">
+<img src="/static/img/oncall/mobile-app-sign-in.png" width="300px">
+
+### Where can I find my QR code?
+
+To access your QR code:
+
+1. Open Grafana OnCall from your desktop
+1. Navigate to the **Users** tab, then tap **View my profile**
+1. tap **Mobile app connection** in your profile
+
+>**Note**: The QR code will timeout for security purposes - Screenshots of the QR code are unlikely to work for authentication.
+
+### Connect to your open source Grafana OnCall account
+
+Grafana OnCall OSS relies on Grafana Cloud as on relay for push notifications.
+You must first connect your Grafana OnCall OSS to Grafana Cloud for the mobile app to work.
+
+To connect to Grafana Cloud, refer to the Cloud page in your OSS Grafana OnCall instance.
+
+For Grafana OnCall OSS, the QR code includes an authentication token along with a backend URL.
+Your Grafana OnCall OSS instance should be reachable from the same network as your mobile device, preferably from the internet.

docs/sources/mobile-app/on-call-status-and-shifts/index.md

@@ -0,0 +1,18 @@
+---
+canonical: https://grafana.com/docs/oncall/latest/mobile-app/on-call-status-and-shifts/
+keywords:
+  - Mobile App
+  - oncall
+  - notification
+  - on-call status
+  - on-call shift
+title: On-call status and shifts
+weight: 500
+---
+
+# On-call status and shifts
+
+On the **Feed** page, your avatar on top of the screen indicates whether you are oncall, will be on call soon, or not.
+Tap on it to open the **upcoming shifts** view.  This view presents your current, and next upcoming shifts (if any), up to 1 month into the future.
+
+<img src="/static/img/oncall/mobile-app-shifts.png" width="300px">

docs/sources/mobile-app/push-notifications/index.md

@@ -0,0 +1,74 @@
+---
+canonical: https://grafana.com/docs/oncall/latest/mobile-app/push-notifications/
+keywords:
+  - Mobile App
+  - oncall
+  - notification
+  - push notification
+title: Push notifications
+weight: 200
+---
+
+# Push notifications
+
+There are three types of push notifications for the mobile app:
+
+- **Mobile push** - Sends a typical push notification to your mobile device.  Intended for all types of alerts.
+- **Mobile push important** - Sends a push notification for important alerts.  We recommend (and default) to louder notifications.
+- **On-Call Shift Notifications** - Sends announcements for upcoming shifts (optional).
+
+## Add mobile app to notification policies
+
+To receive push notifications from the Grafana OnCall mobile app, you must add them to your notification policy steps.
+**Important notifications** should include **Mobile push important** and **Default notifications** should include **Mobile push**.
+
+In the **Settings** tab of the mobile app, tap on **Notification policies** to review, reorder, remove, add or change steps.  
+Alternatively, you can do the same on desktop. From Grafana OnCall, navigate to the **Users** page, click **View my profile** and navigate to the **User Info** tab.
+
+<img src="/static/img/oncall/mobile-app-notification-policies.png" width="300px">
+
+## Configuration
+
+Use the **Push notifications** section in the **Settings** tab to configure push notifications.
+
+You can always confirm how a notification is presented by going to Grafana OnCall on your desktop,
+navigate to the **Users** page, click **View my profile** and navigate to the **Mobile App connection** tab.
+Here you can send a test notification of default or important priority.
+
+### Android
+
+On Android, we leverage the "Notification channels" system feature.
+Each type of notification (**important**, **default**, and **on-call shifts**) registers a channel.
+In this channel, you may configure the sound style, optional Do Not Disturb override, vibration, and so on.
+**Customize notifications** takes you to this system menu, while hitting the **back** button or swiping left (if enabled) takes you back to the application.
+
+**Volume Override** can optionally be configured in the mobile app itself.
+Confusingly, this requires you to provide the **Override Do Not Disturb** permission to the application, in the system configuration.
+The app will prompt for this if applicable.
+
+>**Note**: You can explore included sounds and recommendations via the **Sound Library** button, but to change the sound, go to **Customize notifications**.
+
+<img src="/static/img/oncall/mobile-app-v1-android-settings.png" width="300px">
+<img src="/static/img/oncall/mobile-app-v1-android-push-notifications-prompt.png" width="300px">
+<!-- not showing these images because we don't have a nice way to show this many -->
+<!-- <img src="/static/img/oncall/mobile-app-v1-android-push-notifications.png" width="300px"> -->
+<!-- <img src="/static/img/oncall/mobile-app-v1-android-important-channel-1.png" width="300px"> -->
+<img src="/static/img/oncall/mobile-app-v1-android-important-channel-2.png" width="300px">
+<img src="/static/img/oncall/mobile-app-v1-android-sound-recommendation.png" width="300px">
+
+### iOS
+
+On iOS, all configuration (such as sound selection, Do Not Disturb override, etc) happens inside the app.
+
+For every type of notification (**important**, **default**, and **on-call shifts**), you can configure the sound and its style (constant vs intensifying).
+
+You can also enable or disable Do Not Disturb override for **important** notifications.
+
+<img src="/static/img/oncall/mobile-app-settings-iphone.png" width="300px">
+<img src="/static/img/oncall/mobile-app-sound-recommendation.png" width="300px">
+
+### On-call shift notifications
+
+On-call shift notifications are sent to announce upcoming shifts, roughly ~15 minutes in advance.
+
+To enable or disable on-call shift notifications, use the **On-call shift notifications** section in the **Push notifications** settings.