postshop-backend/manual.md

Mobile App Integration Manual

Overview

This document outlines the initialization flow for the mobile application, specifically focusing on the version check process ensuring users are on the latest or a supported version of the app.

App Launch Flow

When the mobile application launches, it must perform a version check against the API to determine if an update is available or mandatory.

Flow Logic

1. App Launch: User opens the application.
2. Check Version: The app sends a request to the API with its current version and operating system.
3. Handle Response:
   • Update Required: If the update is critical/mandatory, show a blocking modal. The user cannot dismiss it and must click a button to go to the App Store or Google Play Store.
   • Update Optional: If a new version is available but not mandatory, show a dismissible notification or modal suggesting the user to update for a better experience.
   • Latest Version: If the app is up-to-date, proceed to the app home screen silently.
   • Version Not Found: If the version is not recognized (e.g., development build), do not show any update prompts.

API Reference

Check App Version

Endpoint POST /api/app-version

Description Checks if the provided app version is the latest, requires an update, or is optional.

Headers

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

Request Body

Parameter	Type	Required	Description
version	string	Yes	The current version of the mobile app (e.g., "1.0.0").
os	string	Yes	The operating system. Values: ios, android.

Example Request

{
    "version": "1.0.0",
    "os": "ios"
}

Responses

The API returns a JSON object with an update key indicating the status.

Status Value	Meaning	Action Required
latest	App is up to date.	None.
required	A critical update is available.	Block user, redirect to store.
optional	A new version is available.	Notify user, allow optional update.
version-not-found	Version unknown.	None (treat as latest).

Response Examples

Latest Version:

{
    "update": "latest"
}

Required Update:

{
    "update": "required"
}

Optional Update:

{
    "update": "optional"
}