Learner Assistant embedding using an iframe
Overview
Adobe Learning Manager (ALM) users can embed the Learner Assistant directly into their own learner-facing applications (for example, custom portals, LMS front ends, learning hubs, etc.) using a standard HTML <iframe>.
When embedded via iFrame, the Learner Assistant provides access to all Learner Assistant capabilities, including:
- Orchestrator
- Answer Agent
- Knowledge Agent
- Learning Path Agent
Prerequisites
Before you begin, make sure you have:
- An ALM tenant with Learner Assistant enabled. Configure the required catalog(s) from the administrator settings page.
- A valid accessToken for authenticating the learner (or admin) session. To generate an access token, follow the instructions on the Authentication using OAuth 2.0 page. The page includes the steps required to authenticate and generate the access token needed to proceed.
- The ability to embed an
<iframe>in your application and communicate with it via the browser’s postMessage API. - Front-end code ownership of the parent application, since your application must listen for and respond to messages from the embedded iFrame.
Learning Assistant configuration parameters
Initialize iFrame
Pass the configuration to the Learner Assistant via the postMessage API, using an embedded iFrame configuration handshake.
-
The parent application embeds the Learning Assistant as an
<iframe>. -
If no URL-based configuration is found, the Learning Assistant sends an ALM_CHAT_REQUEST_CONFIG event to the parent application.
-
The parent application responds with an ALM_CHAT_CONFIG event containing the configuration payload. For example:
code language-json { "hostName": "learningmanager.adobe.com", "accessToken": "token123", "openByDefault": false, "isAdmin": false } -
After successful initialization, the Learner Assistant renders and is ready to use.
iFrame event summary
The Learner Assistant and the parent application communicate through postMessage events in both directions.
Outgoing events (Learner Assistant iFrame to Parent App)
Incoming events (Parent App to Learner Assistant)
Event-handling requirements in the parent application
Embedding the Learner Assistant via iFrame does not make it a fully self-contained widget. Your parent application must actively listen for outgoing events and take the appropriate action. At a minimum, your application should:
- Listen for ALM_CHAT_REQUEST_CONFIG and respond with ALM_CHAT_CONFIG so the assistant can initialize.
- Handle ALM_CHAT_LO_REDIRECT: when a learner clicks a citation or source in the assistant’s reply, your application receives the loId, loType, and instanceId, and is responsible for navigating the learner to the correct course or learning object.
- Handle ALM_CHAT_URL_REDIRECT: when a learner clicks an external link in a chat message, your application receives the url and is responsible for opening or navigating to it (for example, in a new tab).
- Optionally track ALM_CHAT_OPENED / ALM_CHAT_CLOSED / ALM_CHAT_WAITING_FOR_REPLY to reflect the assistant’s state in your own UI (for example, showing a loading indicator while isWaitingForReply is true).
- Optionally use ALM_CHAT_OPEN / ALM_CHAT_CLOSE / ASK_AI_ASSISTANT_QUERY to control the assistant programmatically. For example, opening the assistant and pre-filling a query from a Help button elsewhere in your application.
Need help?
Reach out to your Adobe Customer Success Manager to set up a technical walkthrough.