Totara Mobile plugin

Owned by Chris Snyder
Sept 08, 2020

This plugin is provided to support the standard Totara Mobile app.

It is disabled by default. To enable and configure it, go to Plugins > Mobile > Mobile settings.

Testing or troubleshooting using the Mobile Device Emulator

An HTML + JavaScript endpoint is included for developers that emulates key behaviour of the Totara Mobile app. It is disabled by default.

  1. Add $CFG->mobile_device_emulator = true; to your config.php
  2. Enable the mobile plugin.
  3. Point your desktop web browser at /totara/mobile/device_emulator.php
  4. Log in using any valid username and password.
  5. You can submit GraphQL persisted queries using the GraphQL browser.
  6. Any pluginfile.php links are handled automatically; click to emulate downloading the file.
  7. Use a totara_mobile_create_webview query (see sample below) to open a URL in the WebView window.

If you see a 'Mobile access error' click the Log out link at the bottom of the page, and resubmit the totara_mobile_create_webview query.

Some sample queries

Basic information about the current user:

{
"operationName" : "totara_mobile_me",
"variables" : {}
}

List of current learning items:

{
"operationName" : "totara_mobile_current_learning",
"variables" : {}
}

Detailed information about a course:

{
"operationName" : "totara_mobile_course",
"variables" : {"courseid": 2}
}

Create a WebView of a URL (opens in emulated WebView browser):

{
"operationName" : "totara_mobile_create_webview",
"variables" : {"url" : "/course/view.php?id=2"}
}

Remove the current device registration

{
"operationName" : "totara_mobile_delete_device",
"variables" : {}
}

Behind the scenes

If you are unable to use the device emulator or want to submit queries and work with endpoints directly, see the sections below.

Registering a new user device from the app

  1. Use a regular browser to log in as a Site Administrator and enable the mobile plugin.
  2. Then the Totara Mobile app should open the site login page in new WebView with TOTARA_MOBILE_DEVICE_REGISTRATION HTTP request header that contains the app name and version.
  3. After a successful log in the user is taken to the /totara/mobile/device_request.php page which contains a secret setup code (in data attribute of the success message).
  4. Ideally the app should then reload the page in WebView to log the user out automatically.
  5. Then the app should make a simple Curl POST request to the /totara/mobile/device_register.php script with json encoded object in request body, for example {"setupsecret" : "1DFPnot6fVV99dvfhjrOf2JDtiM6Om"}.
  6. The returned data structure contains API key and GraphQL endpoint URL. The app is expected to store the API key in secure storage.

If you do not have a mobile app, you can emulate WebView by adding the following temporarily to your config.php

$_SERVER['HTTP_X_TOTARA_MOBILE_DEVICE_REGISTRATION'] = 'Regular browser hack v1';

Manual execution of persisted GraphQL queries

Create PhpStorm HTTP scratch with following text, change POST URL and API-KEY header value to match your site and device registration:

POST http://localhost:8080/totara/mobile/api.php
Accept: application/json
X-API-KEY: vzW4My45Z41i8KKXGy53RxCYZz5LFHkbk8BT1Jbrk56qrSx9BE

{
"operationName" : "totara_mobile_me",
"variables" : {}
}

Manually initiate WebView with user session for embedding in mobile app

  1. Execute totara_mobile_create_webview persisted GraphQL mutation to obtain a secret header token, you need to specify requested URL as parameter.
  2. Create a new WebView with /totara/mobile/device_webview.php URL in mobile app with HTTP request header TOTARA_MOBILE_WEBVIEW_SECRET containing previously obtained secret.
  3. New user session is automatically created without visiting login page and WebView is redirected to previously specified URL.
  4. When WebView is not necessary any more mobile app should execute totara_mobile_delete_webview persisted GraphQL mutation.

You can fake WebView in regular browser by adding following to your config.php

$_SERVER['HTTP_X_TOTARA_MOBILE_WEBVIEW_SECRET'] = '8yWXYXrCgG9QGCZkz0YyBxhxFXajXN';

Examples

POST http://localhost:8080/totara/mobile/api.php
Accept: application/json
X-API-KEY: vzW4My45Z41i8KKXGy53RxCYZz5LFHkbk8BT1Jbrk56qrSx9BE

{
"operationName" : "totara_mobile_create_webview",
"variables" : {"url" : "/course/view.php?id=5"}
}

POST http://localhost:8080/totara/mobile/api.php
Accept: application/json
X-API-KEY: vzW4My45Z41i8KKXGy53RxCYZz5LFHkbk8BT1Jbrk56qrSx9BE

{
"operationName" : "totara_mobile_delete_webview",
"variables" : {"secret" : "8yWXYXrCgG9QGCZkz0YyBxhxFXajXN"}
}

Manually unregistering device

  1. Execute totara_mobile_delete_device persisted GraphQL mutation.
POST http://localhost:8080/totara/mobile/api.php
Accept: application/json
X-API-KEY: vzW4My45Z41i8KKXGy53RxCYZz5LFHkbk8BT1Jbrk56qrSx9BE

{
"operationName" : "totara_mobile_delete_device",
"variables" : {}
}