10. Setting Up the Open edX Mobile Applications

This section is intended for those are who are building Open edX mobile applications and customizing an Open edX installation to support their use.

10.1. Accessing the Source Code

There are currently two edX mobile applications, one for iOS and one for Android. You can find the source code and additional documentation for each application here.

10.2. Configuring Mobile Application Features

For the mobile API and authentication to work correctly with the edX mobile applications, you enable them in the lms.env.json file. You then complete the setup for authentication by creating OAuth clients and adding their IDs to the custom configuration file of each mobile application.

10.2.1. Enable Mobile Application Features

Note

Configuration settings added to the lms.env.json file are reset to their default values when you use Ansible to update edx-platform.

To enable the mobile application features, follow these steps.

  1. In the edx/app/edxapp/lms.env.json file, add the following lines to the features section.

    "FEATURES" : {
        ...
        "ENABLE_MOBILE_REST_API": true,
        "ENABLE_OAUTH2_PROVIDER": true,
        "ENABLE_COMBINED_LOGIN_REGISTRATION": true
    }
    
  2. Save the edx/app/edxapp/lms.env.json file.

  3. Restart the server.

10.2.2. Create the OAuth Clients

You create an OAuth client ID and secret that are specific to your installation for use by the mobile applications. The procedure that follows assumes that you create a different client for each of the edX mobile applications.

Before you can create OAuth clients, a superuser must exist on the server. For more information, see edX Managing the Full Stack.

To create your OAuth clients, follow these steps.

  1. Log in to the Django administration console for your base URL. For example, http://{your_URL}/admin.
  2. In the Oauth2 section, select Clients.
  3. Select Add client. A dialog box opens with the Client id and Client secret populated for the new client.
  4. Enter a Url and Redirect Url for the first application. For example, https://{your_URL}/api/mobile/{version}/?app=ios. While the console requires values for these fields, they are not used by the edX mobile applications. You can enter the same value in both fields.
  5. For the Client type, select Public.
  6. Optionally, enter a User and an identifying Name.
  7. Select Save and add another.
  8. Repeat steps 4-6 for the second application, and then select Save.

10.2.3. Configure the Applications with OAuth Client IDs

The procedure that follows assumes that you have a different OAuth client ID for each edX mobile application.

To configure each edX mobile application with its OAuth client ID, you add a setting to its corresponding custom configuration .yaml file. For information about how to set up custom configuration directories and files, see the GitHub repositories for iOS and Android.

  1. Obtain the OAuth client id for the first application from your Django administration console. For more information, see Create the OAuth Clients.

  2. In your custom GitHub configuration directory, edit the .yaml file for the edX mobile application for iOS. For example, edit your ios.yaml file.

  3. Add the following line to the .yaml file.

    OAUTH_CLIENT_ID: '{client_id_for_iOS_app}'
    
  4. Save the file.

  5. Repeat steps 1-4 for the edX mobile application for Android.

10.3. Configuring Video Modules for Mobile

Courseware videos must be specifically prepared to ensure that they are in mobile accessible formats. Video modules in mobile-available courses should have low resolution encodings that are readily accessible by mobile devices.

After you obtain a low resolution encoding for a video file and post it online, your course team can add its location to the video module that includes the video in the course structure.

  • To configure a video module in edX Studio, you edit the video component. On the Advanced tab, in the Video File URLs field, enter the URL to the mobile-targeted video as the first URL in the list. For more information, see Working with Video Components in Building and Running an Open edX Course.
  • To configure a video module by editing the course XML, enter the URL to the mobile-targeted video as the first URL in the list of html5_sources. For more information, see Video Components in the edX Open Learning XML Guide.

10.4. Enabling Push Notifications

You enable push notifications on the server and then configure each of the edX mobile applications. Currently, you can use Parse for notification delivery.

The procedures that follow assume that you have obtained an application ID, REST API key, and client key from Parse.

10.4.1. Enable Push Notification on the Server

To enable the push notification feature, follow these steps.

  1. In the edx/app/edxapp/cms.auth.json file, add the following lines.

    PARSE_KEYS = {
    
      "APPLICATION_ID": "{app_id}",
    
      "REST_API_KEY": "{API_key}"
    
    }
    
  1. Save the edx/app/edxapp/cms.auth.json file.
  2. Restart the server.
  3. Log in to the Django administration console for your Studio URL. For example, http://studio.{your_URL}/admin.
  4. In the Contentstore section, select Push notification configs.
  5. Select Add push notification config.
  6. Verify that Enabled is selected, and then select Save.

10.4.2. Configure Push Notification on the Clients

The procedure that follows assumes that you use a single set of Parse credentials for both of the edX mobile applications.

You add push notification settings to the applicable custom configuration .yaml file. For information about how to set up custom configuration directories and files, see the GitHub repositories for iOS and Android.

  1. In your custom GitHub configuration directory, edit the .yaml file that stores configuration settings that are common to both of the edX mobile applications. For example, edit your shared.yaml file.

  2. Add the following lines to the .yaml file.

    PARSE:
      NOTIFICATIONS_ENABLED: true
      APPLICATION_ID: {your application id}
      CLIENT_KEY: {your client key}
    
    PUSH_NOTIFICATIONS: true
    
  3. Save the file.