> For the complete documentation index, see [llms.txt](https://docs.snapfix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.snapfix.com/product/features/account/app-launch.md).

# App launch

{% hint style="info" %}
Draft, written by an agent and not yet checked by a person ([how to read these docs](https://docs.snapfix.com/how-to-read.md)). [Source on GitHub](https://github.com/snapfix/docs/blob/main/product/features/app-launch.md).
{% endhint %}

When a **mobile app** starts, it checks the phone, chooses the first screen, and makes sure the phone holds the signed-in person's site data before work starts. A phone that is **jailbroken** (iOS) or **rooted** (Android) sees only a blocked screen. A new install shows the **walkthrough** once. After sign-in, the app runs the **data download**, which copies the person's sites, groups and tasks to the phone; the screen for it says "Reloading Snapfix". The same download runs when a person chooses **Reload** in the side menu. The Android app also moves its local database to a new format when a new version needs it. The web app has no launch screens: a browser load opens the last page or [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md), and there is no local copy of the data.

## Rules

### Device check

* The iOS app checks for a jailbroken device on every launch, before the splash screen. The Android app checks on the splash screen each time it opens. A device that fails the check gets only the blocked screen, and no other screen opens ([Device blocked](https://docs.snapfix.com/how-the-apps-work/screens/account/device-blocked.md#actions)).
* Android skips the check in debug builds. It fails when the build is signed with test keys or when one of three system files exists. A rooted phone that hides those files passes ([Device blocked](https://docs.snapfix.com/how-the-apps-work/screens/account/device-blocked.md#platform-differences), android @ 86068bfeea, `SplashActivity.java:200-228`).
* The check runs on the phone, so it works the same offline.

### Splash screen

* The [Splash screen](https://docs.snapfix.com/how-the-apps-work/screens/account/splash.md) shows while the app decides where to go. On iOS it shows the tagline "If you can Snap it, you can Fix it !" with the date and time for one second. On Android the logo animation plays while the app reads a pending link.
* iOS adds two columns to its local database on the splash screen, with no progress shown.

### Where the app goes next

* A signed-in person with a temporary password gets [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md) before the app opens. On iOS and Android this check comes first ([Splash screen](https://docs.snapfix.com/how-the-apps-work/screens/account/splash.md#actions)).
* iOS checks the walkthrough before the session: a signed-in person who has not seen it gets it first. Android checks the walkthrough only when no one is signed in.
* An account with no site goes to the start-or-join setup ([Start or join](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/start-or-join.md)). On iOS, and on Android after a password sign-in, the setup does not open, because the sign-in sets its flag to 0 \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)].
* A signed-in person goes to [Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md) when a reload is pending (Android also when the local database was updated), and straight to Home otherwise (ios @ aa31967ac8, `SplashScreenVC.swift:258-274`; `SplashActivity.java:523-532`).
* On Android a link that opened the app is handled before the normal route: a group or task link opens its target, an `opnLogin` link opens [Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md), and an onboarding link with a name and email opens [Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md). A pending invitation or reset link opens its handler. Links are described in [Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md).
* On iOS a tap on a push notification opens its target when the app starts. A chat opens the Fix tab and the chat; a task opens its group and the task. If the group is not on the phone yet, nothing opens and the normal route runs ([Splash screen](https://docs.snapfix.com/how-the-apps-work/screens/account/splash.md#actions)).

### Walkthrough

* The [Walkthrough](https://docs.snapfix.com/how-the-apps-work/screens/account/walkthrough.md) has three slides, with "Skip" and a next button, and is shown once, before sign-in.
* iOS marks it seen when the person leaves it, by "Skip" or by the last button. Android marks it seen when it opens, so closing the app during the slides means it is not shown again ([Walkthrough](https://docs.snapfix.com/how-the-apps-work/screens/account/walkthrough.md#platform-differences)).
* On iOS an invitation link also marks the walkthrough seen, so a new user who opens an invitation does not see the slides.
* iOS slides are full images (their animations are switched off in code) and "Skip" hides on the last slide. Android pairs each picture with a title ("Report & Resolve Issues Quicker", "Better Team Communication", "Make Informed Decisions"), and "Skip" reads "Continue" on the last slide ([Walkthrough](https://docs.snapfix.com/how-the-apps-work/screens/account/walkthrough.md#layout)).

### Data download

* The download first uploads changes made offline, then empties the local database and downloads the person's sites and groups, then each site's data, and stores them on the phone ([Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md#actions)).
* iOS downloads up to 500 tasks per group on this screen and fetches the rest in the background; Android downloads everything on this screen ([Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md#platform-differences)). Android also fetches the notification settings at the end.
* On iOS, signing in again as the same person skips the download when no reload is due (`SmsEmailLoginVC.swift:563-570`).
* Android sets its reload flag at sign-in and in several password screens, so the download runs after each of them (`LoginActivity.kt:475`, `:585`; `LoginWithOTPActivity.kt:310`; `InvitedUserCreateNewPasswordActivity.kt:466`).
* The download starts from the site the person last used ([Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md#inputs)).
* "Reload" in the side menu asks for confirmation first; on iOS the same "Reload" in Settings asks too ([Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md#dialogs-and-sheets), [Settings](https://docs.snapfix.com/how-the-apps-work/screens/account/app-settings.md#actions)).
* A signed-in person who belongs to no group is signed out after the message "Your login was successful but it appears that you are not assigned to any specific Group…" (iOS says "any Account or Group" when the person has no site) and "OK" ([Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md#states)). Membership comes from groups, so a person in a site with no groups is signed out the same way \[[ASK-38](https://github.com/snapfix/docs/blob/main/ASK.md#ask-38-should-a-user-whose-sites-have-no-groups-be-signed-out)].

### Local data

* On Android, all local data is cleared at launch when the build's server mode differs from the one the phone last ran with (live or test). The app then opens the walkthrough or sign-in (`SplashActivity.java:503-509`, `:553-570`).
* On Android the local database is moved to the current format when needed, on [Loading your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/account/data-migration.md). It copies 31 tables, refreshes the endpoint list and then opens the setup or Home. It makes no API calls and needs no connection ([Loading your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/account/data-migration.md#actions)).

### App updates

* On iOS, Home reads two Remote Config values when it loads: `ios_minimum_version` and `ios_current_version`. An app below the minimum gets a full-screen update with no close button. An app below the current version gets a sheet with the release notes, "Update" and "Not Now". "Update" opens the App Store (`BusinessListingVC.swift:143`, `AppUtility.swift:4379-4393`, `AppUpdateVC.swift:63-103`).
* On Android, Home asks Google Play for an update when the Remote Config flag `is_need_to_show_in_app_update` is on. The update is immediate (it blocks the app) when the installed version is below `android_minimum_version`, and flexible otherwise (`BusinessListingActivity.java:3830-3880`).

## Flow

The first screens for a signed-in person and for a new install. The order of the checks differs a little between iOS and Android; see [Splash screen](https://docs.snapfix.com/how-the-apps-work/screens/account/splash.md#actions).

```mermaid
flowchart TD
  start["App starts"] --> device{"Jailbroken or rooted?"}
  device -- yes --> blocked["Device blocked: the app stops"]
  device -- no --> signed{"Signed in?"}
  signed -- no --> walk{"Walkthrough seen?"}
  walk -- no --> intro["Walkthrough"]
  walk -- yes --> signin["Sign in"]
  intro --> signin
  signed -- yes --> temp{"Temporary password?"}
  temp -- yes --> setpw["Set password"]
  temp -- no --> site{"Account has a site?"}
  setpw --> site
  site -- no --> setup["Start or join setup"]
  site -- yes --> migrate{"Android: database migration due?"}
  migrate -- yes --> migration["Loading your Snapfix account"] --> home
  migrate -- no --> pending{"Reload or database update pending?"}
  pending -- yes --> download["Reloading Snapfix"]
  pending -- no --> home["Home"]
  download --> home
  signin -- "data download, unless skipped" --> download
```

## Platforms

| Capability                          | Web | iOS                                                                                                                   | Android                                                                                                                                                                            |
| ----------------------------------- | --- | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Device check (jailbroken or rooted) | no  | yes, on every launch, before the splash                                                                               | yes, on the splash screen                                                                                                                                                          |
| Walkthrough on first launch         | no  | yes                                                                                                                   | yes; marked seen when it opens                                                                                                                                                     |
| Splash screen                       | no  | fixed one second                                                                                                      | until the link check finishes                                                                                                                                                      |
| Links handled at launch             | no  | notification targets                                                                                                  | group, task, `opnLogin`, onboarding and invitation links                                                                                                                           |
| Data download after sign-in         | no  | yes; skipped for the same person when no reload is due                                                                | yes, after every sign-in                                                                                                                                                           |
| First download                      | no  | 500 tasks per group, the rest in the background                                                                       | everything on the screen                                                                                                                                                           |
| Reload from the side menu           | no  | yes, also in Settings                                                                                                 | yes                                                                                                                                                                                |
| Temporary password check at launch  | no  | yes                                                                                                                   | yes                                                                                                                                                                                |
| Setup for an account with no site   | no  | not after sign-in \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] | not after a password sign-in; after SSO or QR sign-up when the server flags it \[[ASK-39](https://github.com/snapfix/docs/blob/main/ASK.md#ask-39-is-the-apps-setup-flow-retired)] |
| Server mode reset                   | no  | no                                                                                                                    | yes                                                                                                                                                                                |
| Local database migration            | no  | silent, on the splash                                                                                                 | yes, on its own screen                                                                                                                                                             |
| Update prompt                       | no  | yes, from Remote Config, on Home                                                                                      | yes, Google Play update, on Home                                                                                                                                                   |

## Screens

* [Splash screen](https://docs.snapfix.com/how-the-apps-work/screens/account/splash.md)
* [Device blocked](https://docs.snapfix.com/how-the-apps-work/screens/account/device-blocked.md)
* [Walkthrough](https://docs.snapfix.com/how-the-apps-work/screens/account/walkthrough.md)
* [Sign in](https://docs.snapfix.com/how-the-apps-work/screens/account/sign-in.md)
* [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md)
* [Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md)
* [Loading your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/account/data-migration.md) (Android)
* [Settings](https://docs.snapfix.com/how-the-apps-work/screens/account/app-settings.md) (iOS "Reload")
* [Start or join setup](https://docs.snapfix.com/how-the-apps-work/screens/onboarding/start-or-join.md)

## API and data

* Data download: the read calls listed in [Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md#actions), for example [`read_parent_data_v2`](https://docs.snapfix.com/engineering-reference/api/tasks.md#post-actionread_parent_data_v2). The groups and their data are in the [Groups API](https://docs.snapfix.com/engineering-reference/api/groups.md).
* The splash screen, device check, walkthrough and migration make no API calls.
* Update prompts read Firebase Remote Config values. No endpoint is involved.
* Tables: the server has none for this step. The app keeps its copy of the data in a local database on the phone.

## Depends on

* [Sign-in](https://docs.snapfix.com/product/features/account/sign-in.md): the sign-in and session rules that decide the first screen.
* [Password reset](https://docs.snapfix.com/product/features/account/password-reset.md): temporary passwords and [Set password](https://docs.snapfix.com/how-the-apps-work/screens/account/set-password.md).
* [Email and SMS links](https://docs.snapfix.com/product/features/account/email-links.md): links that open at launch.
* [Joining a site](https://docs.snapfix.com/product/features/onboarding/join-site.md): Android onboarding links open [Sign up by QR invitation](https://docs.snapfix.com/how-the-apps-work/screens/account/qr-sign-up.md).
* [Site setup in the app](https://docs.snapfix.com/product/features/onboarding/site-setup.md): the start-or-join setup for accounts with no site.
* [Push notifications](https://docs.snapfix.com/product/features/notifications/push-notifications.md): notification taps that open a chat or a task.
* [Profile and settings](https://docs.snapfix.com/product/features/account/profile.md): "Reload" in Settings and the side menu.
* [Groups](https://docs.snapfix.com/product/features/groups/groups.md) and [Tasks](https://docs.snapfix.com/product/features/tasks/tasks.md): the data the download brings to the phone.

## Edge cases

* **Offline:** the first screens work offline. The download needs a connection. Android checks first and offers "Retry" and "Cancel" with the message "You must have internet access to login."; "Cancel" clears the local data and opens sign-in. iOS does not check: an offline attempt counts as a failed attempt, and after three it shows "Account details not found." ([Reloading Snapfix](https://docs.snapfix.com/how-the-apps-work/screens/account/download-data.md#states)).
* **Download errors:** iOS tries three times, then shows "Account details not found." with "OK" (try again) and "Logout". On Android an unexpected server reply clears the local data and shows the same message with "Retry" and "Logout".
* **Large task lists:** iOS fetches the unfrozen tasks in batches of 1,000 and loses all but the first batch.
* **Malformed notification:** a malformed push payload can crash the iOS app when it opens ([Splash screen](https://docs.snapfix.com/how-the-apps-work/screens/account/splash.md#states)).
* **Storage permission:** on Android 6 and later, leaving the walkthrough while signed in with a reload due and without storage permission clears the session and opens sign-in with no message.
* **Migration errors:** a failed copy of the contacts table is logged and skipped. A failed copy of any other table stops the migration with no message, and the app stays on the loading screen ([Loading your Snapfix account](https://docs.snapfix.com/how-the-apps-work/screens/account/data-migration.md#states)).
* **Several sites:** the download starts from the site the person last used. Switching sites is in [Switching sites](https://docs.snapfix.com/product/features/groups/site-switching.md).
* **Time zones:** None.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.snapfix.com/product/features/account/app-launch.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
