Extension Web-app API

This documentation covers:

1. Adding extension web-app in to the mobile app.
2. Resolving session token to obtain the current user info.

1. Adding extension web-app in the mobile app.

By enabling extension web-app in the mobile app, users can access additional features that your school can offer in the form of a web-app. The mobile app will display a “More” button in the side menu. When user tap on it, the main area will open a webpage in the in-app browser, with

Steps:

1. In console, navigate to “Settings” Module > Settings > App Settings.

2. Enable the “More” item.

3. In More: Entrance Page URL, enter the URL for the entrance page of the extension web-app.

Example: for testing purpose, developer can create a temporary request bin at https://hookbin.com , and set the given Hookbin Endpoint to the “More: Entrance Page URL”.

2. Resolving session token to obtain the current user info.

When the in-app browser opens the entrance page, it also passes 5 headers to the page:

1. X-App-Id: The current appId should be “isf2”

2. X-Session-Token: this is a special token that you use to obtain the user account associated to a session.

3. X-Language: the current langauge preference in the app. en or zh.

4. X-SSO-Response: the SSO response if user logged in from SSO. It is the full stringified JSON object, with Base64 encoded.

5. X-Selected-Sub-User-Id: The EDU.INK user ID of the currently selected student in the app. If “all Children” is selected in the app, then the value will be “all”.

6. X-Selected-Sub-Ref-No: The Reference No. of the currently selected student in the app. If “all Children” is selected in the app, then the value will be "" (empty string).

To obtain the user account info by session token, please use this API with the same values of X-App-Id and X-Session-Token:

GET https://isfapi3-staging.isf.edu.hk/v2/grd/external-session // Use this API for Staging
GET https://isfapi3.isf.edu.hk/v2/grd/external-session // Use this API for Production

Headers:
- X-Session-Token: {{sessionToken}}
- X-App-Id: {{appId}}

Response structure:

{
  "userId": 102, // Numeric User ID from EDU.INK
  "appId": "isf2", // String: "isf2"
  "createdAt": "2021-07-23T06:56:49.060Z", // ISO Date String: timestamp of the session creation
  "expireAt": "2022-07-18T06:57:04.402Z", // ISO Date String: the time this session will expire
  "firstName": "Calvin",
  "lastName": "EDUINK-DEV",
  "fullName": "Calvin EDUINK-DEV",
  "chineseName": "",
  "refNo": "102", // User reference no., usually your ISF Account ID.
  "email": "[email protected]",
  "imageUrl": "https://ui-avatars.com/api/?background=FFB900&color=59524F&name=Calvin+EDUINK", // User's avatar image
  "role": "Guardian" // The user's role when using the app. One of "Guardian", "Student", "Staff"
}

Once obtained the user account info, you can then cross-reference it with your local user database, create your own session, and the provide the extended features.