|
| 1 | +1. Offline content generation for mobile OeX app |
| 2 | +============================================= |
| 3 | + |
| 4 | +Status |
| 5 | +------ |
| 6 | + |
| 7 | +Accepted |
| 8 | + |
| 9 | +Context |
| 10 | +------- |
| 11 | + |
| 12 | +The primary goal is to enable offline access to course content in the Open edX mobile application. |
| 13 | +This will allow users to download course materials when they have internet access and access them |
| 14 | +later without an internet connection, also it should support synchronization of the submitted results |
| 15 | +with backend service as connection become available again. This feature is crucial for learners |
| 16 | +in areas with unreliable internet connectivity or those who prefer to study on the go without using mobile data. |
| 17 | +It is possible to provide different kind of content using the Open edX platform, such as read-only materials, |
| 18 | +videos, and assessments. Therefore to provide the whole course experience in offline mode it's required to |
| 19 | +make all these types of content available offline. Of course it won't be feasible to recreate grading |
| 20 | +algorithms in mobile, so it's possible to save submission on the mobile app and execute synchronization |
| 21 | +of the user progres as not limited connectivity is back. |
| 22 | + |
| 23 | +From the product perspective the following Figma designs and product requirements should be considered: |
| 24 | + |
| 25 | +* `Download and Delete (Figma)`_ |
| 26 | +* `Downloads (Figma)`_ |
| 27 | + |
| 28 | +.. _Download and Delete (Figma): https://www.figma.com/design/iZ56YMjbRMShCCDxqrqRrR/Mobile-App-v2.4-%5BOpen-edX%5D?node-id=18472-187387&t=tMgymS6WIZZJbJHn-0 |
| 29 | +.. _Downloads (Figma): https://www.figma.com/design/iZ56YMjbRMShCCDxqrqRrR/Mobile-App-v2.4-%5BOpen-edX%5D |
| 30 | + |
| 31 | +Decision |
| 32 | +-------- |
| 33 | + |
| 34 | +The implementation of the offline content support require addition of the following features to the edx-platform: |
| 35 | + |
| 36 | +* It's necessary to generate an archive with all necessary HTML and assets for a student view of an xBlock, so it's possible to display an xBlock using mobile WebView. |
| 37 | +* Implement a new standard XBlock view called `offline_view` which would generate user-agnostic fragments suitable for offline use. This view will avoid any dependence on student-specific state, focusing solely on content and settings. |
| 38 | +* XBlock classes can opt into supporting `offline_view`. They can implement this view fully or partially. For example, a block that relies on user-specific randomization or interactive elements that require online connectivity would not be rendered offline. |
| 39 | +* The generated offline content should be provided to mobile device through mobile API. |
| 40 | +* To support CAPA problems and other kinds of assessments in offline mode it's necessary to create an additional |
| 41 | + JavaScript layer that will allow communication with Mobile applications by sending JSON messages |
| 42 | + using Android and IOS Bridge. |
| 43 | + |
| 44 | + |
| 45 | +Offline content generation |
| 46 | +~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 47 | + |
| 48 | +Generating zip archive with xBlock data for HTML and CAPA problems |
| 49 | +When content is published in CMS and offline generation is enabled for the course or entire platform using waffle flags, the content generation task should be started for supported blocks. |
| 50 | +Every time block content republished ZIP archive with offline content should be regenerated. |
| 51 | +Supported XBlock class should implement `offline_view` method that will be used to generate the content. |
| 52 | +HTML should be processed, all related assets files, images and scripts should be included in the generated ZIP archive with offline content |
| 53 | +The Generation process should work with local media storage as well as s3. |
| 54 | +If error retrieving block happened, the generation task will be scheduled for retry 2 more times, with progressive delay. |
| 55 | + |
| 56 | + .. image:: _images/mobile_offline_content_generation.svg |
| 57 | + :alt: Mobile Offline Content Generation Process Diagram |
| 58 | + |
| 59 | + |
| 60 | +Offline content deletion |
| 61 | +~~~~~~~~~~~~~~~~~~~~~~~~ |
| 62 | + |
| 63 | +When the course is published and some blocks are removed from the course, related ZIP archive should be deleted. |
| 64 | +When some blocks are removed from the course without publishing the course, the related ZIP archive shouldn't be deleted. |
| 65 | + |
| 66 | + |
| 67 | +Mobile API extension |
| 68 | +~~~~~~~~~~~~~~~~~~~~ |
| 69 | + |
| 70 | +Extend the Course Home mobile API endpoint, and add a new version of the API (url /api/mobile/v4/course_info/blocks/) |
| 71 | +to return information about offline content available for download for supported blocks |
| 72 | + |
| 73 | +.. code-block:: json |
| 74 | + { |
| 75 | + ... |
| 76 | + "offline_download": { |
| 77 | + "file_url": "{file_url}" or null, |
| 78 | + "last_modified": "{DT}" or null, |
| 79 | + "file_size": "" |
| 80 | + } |
| 81 | + } |
| 82 | +
|
| 83 | +
|
| 84 | +JavaScript Bridge for interaction with mobile applications |
| 85 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 86 | +Implement JS Bridge JS script to intercept and send results to mobile device for supported CAPA problems. |
| 87 | + |
| 88 | +The JS bridge will intercept AJAX requests in the mobile application and store the responses locally. If the user submits the response offline he will be shown the message "Your response is accepted" and the Submit button will be disabled as the submission will be sent twice. |
| 89 | +When the internet connection is back the mobile client will submit the cached responses one by one through the regular xBlock handler endpoints. |
| 90 | +Data from submission should be submitted through bridge on iOS and Android devices. |
| 91 | +This script should expose markCompleted JS function so mobile can change state of the offline problem after the data was saved into internal database or on initialization of the problem. |
| 92 | + |
| 93 | +* **Implement of a mechanism for generating and storing on a server or external storage**: The course content should be pre-generated and saved to the storage for later download. |
| 94 | + * **Render block fragment**: Implement a new standard XBlock view called `offline_view` which would generate user-agnostic fragments suitable for offline use. This view will avoid any dependence on student-specific state, focusing solely on content and settings. |
| 95 | + * **Replace static and media**: Save static and media assets files used in block to temporary directory and replace their static paths with local paths. |
| 96 | + * **Archive and store content**: Archive the generated content and store it on the server or external storage. |
| 97 | +* **Mechanism for updating the generated data**: When updating course blocks (namely when publishing) the content that has been changed should be re-generated. |
| 98 | + * **Track course publishing events on CMS side**: Add a new signal `course_cache_updated` to be called after the course structure cache update in `update_course_in_cache_v2`. Add a signal that listens to `course_cache_updated` and starts block generation. |
| 99 | + * **Update archive**: Check generated archive creation date and update it if less than course publishing date. |
| 100 | +* **Implement a Mobile Local Storage Mechanism**: Use the device's local storage to save course content for offline access. |
| 101 | + * **Extend blocks API**: Add links to download blocks content and where it is possible. |
| 102 | +* **Sync Mechanism**: Periodically synchronize local data with the server when the device is online. |
| 103 | + * **Sync on app side**: On course outline screen, check if the course content is up to date and update it if necessary. |
| 104 | + * **Sync user responses**: When the device is offline, save user responses locally and send them to the server when the device is online. |
| 105 | +* **Selective Download**: Allow users to choose specific content to download for offline use. |
| 106 | +* **Full Course Download**: Provide an option to download entire courses for offline access. |
| 107 | + |
| 108 | +Supported xBlocks in offline mode |
| 109 | +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 110 | + |
| 111 | +It was decided to include a fraction of Open edX xBlocks to be supported. |
| 112 | +The following list of blocks is currently planned to be added to the support: |
| 113 | + |
| 114 | +* **Common problems**: |
| 115 | + * **Checkboxes** - full support |
| 116 | + * **Dropdown** - full support |
| 117 | + * **Multiple Choice** - full support |
| 118 | + * **Numerical Input** - full support |
| 119 | + * **Text Input** - full support |
| 120 | + * **Checkboxes with Hints and Feedback** - partial support without Hints and Feedback |
| 121 | + * **Dropdown with Hints and Feedback** - partial support without Hints and Feedback |
| 122 | + * **Multiple Choice with Hints and Feedback** - partial support without Hints and Feedback |
| 123 | + * **Numerical Input with Hints and Feedback** - partially supported without Hints and Feedback |
| 124 | + * **Text Input with Hints and Feedback** - partially supported without Hints and Feedback |
| 125 | + * **Blank Advanced Problems** - partially supported, without loncapa/python problems or multi-part problems |
| 126 | +* **Text**: |
| 127 | + * **Text** - full support |
| 128 | + * **IFrame Tool** - full support |
| 129 | + * **Raw HTML** - full support |
| 130 | + * **Zooming Image Tool** - full support |
| 131 | +* **Video** - already supported |
| 132 | + |
| 133 | + |
| 134 | +Consequences |
| 135 | +------------ |
| 136 | + |
| 137 | +* Enhanced learner experience with flexible access to course materials. |
| 138 | +* Increased accessibility for learners in regions with poor internet connectivity. |
| 139 | +* Improved engagement and completion rates due to uninterrupted access to content. |
| 140 | +* Simplified Maintenance by using a unified rendering view (`offline_view`), the complexity of maintaining separate renderers for online and offline content is significantly reduced. |
| 141 | +* The proposed approach not only caters to the current needs of mobile users but also sets a foundation for expanding offline access to other platforms and uses. |
| 142 | +* Potential increase in app size due to locally stored content. |
| 143 | +* Increased complexity in managing content synchronization and updates. |
| 144 | +* Need for continuous monitoring and updates to handle new content types and formats. |
| 145 | + |
| 146 | +Rejected Solutions |
| 147 | +------------------ |
| 148 | + |
| 149 | +* **Store common .js and .css files of blocks in a separate folder:** |
| 150 | + * This solution was rejected because it is unclear how to track potential changes to these files and re-generate the content of the blocks. |
| 151 | + |
| 152 | +* **Generate content on the fly when the user requests it:** |
| 153 | + * This solution was rejected because it would require a significant amount of processing power and time to generate content for each block when requested. |
| 154 | + |
| 155 | +* **Separate Offline Renderer**: |
| 156 | + * The initial proposal of creating a separate renderer for offline content was rejected due to the increased complexity and potential for inconsistent behavior between online and offline content. |
0 commit comments