docs: ADR introducing mobile offline content support #35011
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,134 @@ | ||
| Offline content generation for mobile OeX app | ||
| ============================================= | ||
|
|
||
| Status | ||
| ------ | ||
|
|
||
| Proposed | ||
|
|
||
| Context | ||
| ------- | ||
|
|
||
| The primary goal is to enable offline access to course content in the Open edX mobile application. | ||
| This will allow users to download course materials when they have internet access and access them | ||
| later without an internet connection, also it should support synchronization of the submitted results | ||
| with backend service as connection become available again. This feature is crucial for learners | ||
| in areas with unreliable internet connectivity or those who prefer to study on the go without using mobile data. | ||
| It is possible to provide different kind of content using the Open edX platform, such as read-only materials, | ||
| videos, and assessments. Therefore to provide the whole course experience in offline mode it's required to | ||
| make all these types of content available offline. Of course it won't be feasible to recreate grading | ||
| algorithms in mobile, so it's possible to save submission on the mobile app and execute synchronization | ||
| of the user progres as not limited conectivity is back. | ||
| From the product perspective the following Figma designs and product requirements should be considered: | ||
| * `Download and Delete (Figma)`_ | ||
| * `Downloads (Figma)`_ | ||
|
|
||
| .. _Download and Delete (Figma): https://www.figma.com/design/iZ56YMjbRMShCCDxqrqRrR/Mobile-App-v2.4-%5BOpen-edX%5D?node-id=18472-187387&t=tMgymS6WIZZJbJHn-0 | ||
| .. _Downloads (Figma): https://www.figma.com/design/iZ56YMjbRMShCCDxqrqRrR/Mobile-App-v2.4-%5BOpen-edX%5D | ||
|
|
||
| Decision | ||
| -------- | ||
|
|
||
| The implementation of the offline content support require addition of the following features to the edx-platform: | ||
|
|
||
| * 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. | ||
| * The generated offline content should be provided to mobile device through mobile API. | ||
| * To support CAPA problems and other kinds of assessments in offline mode it's necessary to create an additional | ||
| JavaScript layer that will allow communication with Mobile applications by sending JSON messages | ||
| using Android and IOS Bridge. | ||
|
|
||
|
|
||
|
|
||
| Offline content generation | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Generating zip archive with xBlock data for HTML and CAPA problems | ||
| 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. | ||
| Every time block content republished ZIP archive with offline content should be regenerated. | ||
| The xBlock should be rendered the same way it’s rendered for a student using /xblock/{locator.id} endpoint in LMS. | ||
| HTML should be processed, all related assets files, images and scripts should be included in the generated ZIP archive with offline content | ||
| The Generation process should work with local media storage as well as s3. | ||
| If error retrieving block happened, the generation task will be scheduled for retry 2 more times, with progressive delay. | ||
|
|
||
| .. image:: _images/mobile_offline_content_generation.svg | ||
| :alt: Mobile Offline Content Generation Process Diagram | ||
|
|
||
| Mobile API extension | ||
| ~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| Extend mobile API endpoint for Course Home, to return information about offline content available for download for supported blocks | ||
| { | ||
| ... | ||
| "offline_download": { | ||
| "file_url": "{file_url}" or null, | ||
| "last_modified": "{DT}" or null, | ||
| "file_size": "" | ||
| } | ||
| } | ||
|
|
||
| JavaScript Bridge for interaction with mobile applications | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
| Implement JS Bridge JS script to intercept and send results to mobile device for supported CAPA problems | ||
| The submission data should be sent via bridge to IOS and Android devices. | ||
| 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 | ||
|
|
||
|
|
||
| * **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. | ||
| * **Render content**: Generate HTML content of block as it does for LMS. | ||
|
There was a problem hiding this comment. What Python function will call in order to render the HTML? Does that function require a user_id? If so, how will you handle that? There was a problem hiding this comment. The new function will collect the context needed to render the block and call |
||
| * **Replace static and media**: Save static and media assets files used in block to temporary directory and replace their static paths with local paths. | ||
| * **Archive and store content**: Archive the generated content and store it on the server or external storage. | ||
| * **Mechanism for updating the generated data**: When updating course blocks (namely when publishing) the content that has been changed should be re-generated. | ||
| * **Track course publishing events on CMS side**: Signal in the CMS that makes request to LMS to update course content. | ||
| * **Track course publishing events on LMS side**: API endpoint to receive the signal from CMS and update course content. | ||
|
There was a problem hiding this comment. I can see that this would work, but I am curious if there is a more elegant approach. I have asked in There was a problem hiding this comment. So far, we've tried the implementation described in ADR and found a problem that in this case, content generation can occur before the course structure is updated. Therefore, I propose a new attribute for |
||
| * **Update archive**: Check generated archive creation date and update it if less than course publishing date. | ||
| * **Implement a Mobile Local Storage Mechanism**: Use the device's local storage to save course content for offline access. | ||
| * **Extend blocks API**: Add links to download blocks content and where it is possible. | ||
| * **Sync Mechanism**: Periodically synchronize local data with the server when the device is online. | ||
| * **Sync on app side**: On course outline screen, check if the course content is up to date and update it if necessary. | ||
|
Comment on lines
+87
to
+88
There was a problem hiding this comment. Please say more about:
There was a problem hiding this comment. The JS bridge will intercept ajax requests in the mobile application and store the responses. The user will see the message "Your response is accepted" and the Submit button should be disabled. |
||
| * **Selective Download**: Allow users to choose specific content to download for offline use. | ||
| * **Full Course Download**: Provide an option to download entire courses for offline access. | ||
|
|
||
| Supported xBlocks in offline mode | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| It was decided to include a fraction of Open edX xBlocks to be supported. | ||
| The following list of blocks is currently planned to be added to the support: | ||
|
Comment on lines
+96
to
+97
There was a problem hiding this comment. I'm glad you enumerated these. I agree that it makes sense to start with a subset of XBlocks. I think it would be good to keep the door open for future XBlocks to be supported. Could you build this in a way that would allow that? For example, can we make sure that it is possible to add support for an external XBlock like xblock-drag-and-drop-v2, without adding knowledge of xblock-drag-and-drop-v2 to edx-platform? Relatedly, please keep in mind that we are extracting all built-in edx-platform XBlocks into a separate repo. It will take some time, but the CAPA ProblemBlock will eventually be extracted as part of that project. So, when you implement this, it is important that we are not hard-coding more CAPA knowledge into the publishing process-- the CAPA-specific archiving code should stay within the ProblemBlock definition. There was a problem hiding this comment. Thank you for your question! As for your question about xblock-drag-and-drop-v2 or other external XBlocks, yes, we won't need to add changes to the edx platform for each of them. I think that some refactoring/improvements will be needed in the future to expand the types of supported blocks, but it definitely shouldn't be for each new block separately. As for CAPA, yes, the CAPA block will not be used. There was a problem hiding this comment.
@NiedielnitsevIvan Can you clarify this statement? "CAPA" is just another name for the ProblemBlock, which implements most of the core problem types. To implement offline support for most problems, the app will need to download archives of CAPA problem data and render CAPA html/javascript. There was a problem hiding this comment. Sorry, I probably misunderstood the question. |
||
|
|
||
| * **Common problems**: | ||
| * **Checkboxes** - full support | ||
| * **Dropdown** - full support | ||
| * **Multiple Choice** - full support | ||
| * **Numerical Input** - full support | ||
| * **Text Input** - full support | ||
| * **Checkboxes with Hints and Feedback** - partial support without Hints and Feedback | ||
| * **Dropdown with Hints and Feedback** - partial support without Hints and Feedback | ||
| * **Multiple Choice with Hints and Feedback** - partial support without Hints and Feedback | ||
| * **Numerical Input with Hints and Feedback** - partially supported without Hints and Feedback | ||
| * **Text Input with Hints and Feedback** - partially supported without Hints and Feedback | ||
| * **Text**: | ||
| * **Text** - full support | ||
| * **IFrame Tool** - full support | ||
| * **Raw HTML** - full support | ||
| * **Zooming Image Tool** - full support | ||
| * **Video** - already supported | ||
|
|
||
|
|
||
| Consequences | ||
| ------------ | ||
|
|
||
| * Enhanced learner experience with flexible access to course materials. | ||
| * Increased accessibility for learners in regions with poor internet connectivity. | ||
| * Improved engagement and completion rates due to uninterrupted access to content. | ||
| * Potential increase in app size due to locally stored content. | ||
| * Increased complexity in managing content synchronization and updates. | ||
| * Need for continuous monitoring and updates to handle new content types and formats. | ||
|
|
||
| Rejected Solutions | ||
| ------------------ | ||
|
|
||
| Store common .js and .css files of blocks in a separate folder: | ||
| * This solution was rejected because it is unclear how to track potential changes to these files and re-generate the content of the blocks. | ||
|
|
||
| Generate content on the fly when the user requests it: | ||
| * This solution was rejected because it would require a significant amount of processing power and time to generate content for each block when requested. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please provide the exact URL
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added