FamilyInvite PageDocs

Project: Pet Feeder | page_id: 1746

Family Invitation Page Interface Documentation

Overview

• Path: /invite/:code
• Method: GET
• Authentication required: No (public route)
• Response type: text/html; charset=utf-8
• Description: Returns an H5 invitation landing page. When there is no token, a download guide page is displayed; when a valid token is carried, it automatically attempts to join the family and returns a result page.

Path Parameters

Optional Authentication Parameters

This interface supports two ways of passing in the user's JWT Token, used to automatically complete the join action within the H5 page:

Priority: request header > query parameter. When no token is carried, a page guiding the user to open or download the App is displayed.

Page Behavior Description

Deep Link Format

Response Examples

1. No token carried (guide page)

GET /invite/abc123xyz

Returns HTTP 200 with Content-Type: text/html; charset=utf-8. The page content is as follows:

🐾 A friend has invited you to join a family
Click the button below to view the invitation details in the App and join the family.

[Already have the App? Click here to open]   → xunswei://invite/abc123xyz
[Download the App]             → {AppDownloadURL}

2. Valid token carried, join successful

GET /invite/abc123xyz?token=<JWT>

Returns HTTP 200. The page content is as follows:

✅ Joined successfully!
You have successfully joined the family "My Family". Please return to the App to view the family information.

[View in the App]  → xunswei://family/{familyId}

3. Invalid token or join failed

GET /invite/abc123xyz?token=<invalidJWT>

Returns HTTP 200. The page content is as follows:

⚠️ Invitation invalid
The login information has expired. Please log in to the App again.

[Already have the App? Click here to open]   → xunswei://invite/abc123xyz
[Download the App]            → {AppDownloadURL}

Usage Flow

1. The App calls POST /api/family/invite to obtain the invitation code and invitation link
2. The user shares the link with a friend (the link looks like [https://example.com/invite/{code})](https://example.com/invite/{code}))
3. The friend opens the link in a browser:
   a. App not installed → click the "Download App" button
   b. App installed → click "Open in App" to trigger the Deep Link, then after entering the App call
      POST /api/family/join to complete joining
   c. The H5 page carries a token → joins automatically, no need to jump to the App

Invitation Code Validity Period

The invitation code is generated by /api/family/invite and is valid for 24 hours (86400 seconds). After it expires, visiting this page will display the "Invitation invalid" page.

Notes

• This interface always returns HTTP 200; different states are distinguished by the page content, and the unified JSON response format is not used.
• AppDownloadURL is determined by the server-side configuration item server.app_download_url.
• The interface has no cross-origin restrictions and can be accessed directly in a browser.