Fix: subEntityId not passed to app when deeplink clicked from within target channel

packages/teams-js/src/internal/handlers.ts

@@ -268,6 +268,7 @@ function convertToResumeContext(context: LoadContext): ResumeContext {
   return {
     entityId: context.entityId,
     contentUrl: new URL(context.contentUrl),
+    ...(context.subEntityId !== undefined && { subPageId: context.subEntityId }),
   };
 }
 

packages/teams-js/src/public/interfaces.ts

@@ -1038,6 +1038,13 @@ export interface ResumeContext {
    * The content URL that is requested to be loaded
    */
   contentUrl: URL;
+
+  /**
+   * The developer-defined unique ID for the sub-page to navigate to within the entity. This field is
+   * populated from the `subEntityId` parameter of the deep link that triggered the app load/resume.
+   * It corresponds to {@link app.PageInfo.subPageId | app.Context.page.subPageId}.
+   */
+  subPageId?: string;
 }
 
 /**
@@ -1054,6 +1061,12 @@ export interface LoadContext {
    * The content URL that is requested to be loaded
    */
   contentUrl: string;
+
+  /**
+   * The developer-defined unique ID for the sub-entity to navigate to within the entity.
+   * Since {@link LoadContext} is deprecated, please use {@link ResumeContext.subPageId} instead.
+   */
+  subEntityId?: string;
 }
 
 /** Represents information about a frame within a tab or dialog module. */

packages/teams-js/test/public/app.spec.ts

@@ -19,6 +19,7 @@ import {
   FileOpenPreference,
   LoadContext,
   M365ContentAction,
+  ResumeContext,
   SecondaryM365ContentIdName,
 } from '../../src/public/interfaces';
 import {
@@ -1114,6 +1115,36 @@ describe('Testing app capability', () => {
             await utils.sendMessage('load', loadContext);
             expect(handlerInvoked).toBe(true);
           });
+
+          it(`app.lifecycle.registerOnResumeHandler should pass subPageId from load context subEntityId. context: ${context}`, async () => {
+            await utils.initializeWithContext(context);
+
+            const loadContextWithSubEntityId: LoadContext = {
+              entityId: 'testEntityId',
+              contentUrl: 'https://localhost:4000',
+              subEntityId: 'testSubPageId',
+            };
+
+            let receivedResumeContext: ResumeContext | undefined;
+            app.lifecycle.registerOnResumeHandler((ctx: ResumeContext) => {
+              receivedResumeContext = ctx;
+            });
+            await utils.sendMessage('load', loadContextWithSubEntityId);
+            expect(receivedResumeContext).toBeDefined();
+            expect(receivedResumeContext?.subPageId).toBe('testSubPageId');
+          });
+
+          it(`app.lifecycle.registerOnResumeHandler should have undefined subPageId when load context has no subEntityId. context: ${context}`, async () => {
+            await utils.initializeWithContext(context);
+
+            let receivedResumeContext: ResumeContext | undefined;
+            app.lifecycle.registerOnResumeHandler((ctx: ResumeContext) => {
+              receivedResumeContext = ctx;
+            });
+            await utils.sendMessage('load', loadContext);
+            expect(receivedResumeContext).toBeDefined();
+            expect(receivedResumeContext?.subPageId).toBeUndefined();
+          });
         });
       });
     });
@@ -2104,6 +2135,29 @@ describe('Testing app capability', () => {
             } as DOMMessageEvent);
             expect(handlerInvoked).toBe(true);
           });
+
+          it(`app.lifecycle.registerOnResumeHandler should pass subPageId from load context subEntityId. context: ${context}`, async () => {
+            await utils.initializeWithContext(context);
+
+            const loadContextWithSubEntityId: LoadContext = {
+              entityId: 'testEntityId',
+              contentUrl: 'https://localhost:4000',
+              subEntityId: 'testSubPageId',
+            };
+
+            let receivedResumeContext: ResumeContext | undefined;
+            app.lifecycle.registerOnResumeHandler((ctx: ResumeContext) => {
+              receivedResumeContext = ctx;
+            });
+            await utils.respondToFramelessMessage({
+              data: {
+                func: 'load',
+                args: [loadContextWithSubEntityId],
+              },
+            } as DOMMessageEvent);
+            expect(receivedResumeContext).toBeDefined();
+            expect(receivedResumeContext?.subPageId).toBe('testSubPageId');
+          });
         });
       });
     });

packages/teams-js/test/public/teamsAPIs.spec.ts

@@ -174,6 +174,27 @@ describe('Testing TeamsCore Capability', () => {
 
           expect(handlerInvoked).toBe(true);
         });
+
+        it(`teamsCore.registerOnLoadHandler should pass subEntityId from load context. context: ${context}`, async () => {
+          await utils.initializeWithContext(context);
+
+          const loadContextWithSubEntityId: LoadContext = {
+            entityId: 'testEntityId',
+            contentUrl: 'https://localhost:4000',
+            subEntityId: 'testSubEntityId',
+          };
+
+          let receivedContext: LoadContext | undefined;
+          teamsCore.registerOnLoadHandler((ctx: LoadContext) => {
+            receivedContext = ctx;
+            return false;
+          });
+
+          await utils.sendMessage('load', loadContextWithSubEntityId);
+
+          expect(receivedContext).toBeDefined();
+          expect(receivedContext?.subEntityId).toBe('testSubEntityId');
+        });
       });
     });