@synopackageland/sdk 0.12.1 → 0.12.2

package/README.md

@@ -83,6 +83,40 @@ so the DSM window's ctx works as it is.
 <AppShell v-model="page" :ctx="ctx" :locale="ctx.locale" :pages="pages" sidebar-storage-key="HelloGo" />
 ```
 
+## Launch links
+
+A DSM desktop link opens the App's window on one of its pages:
+`https://<nas>:5001/?launchApp=SYNO.SDS.<package>.Instance&launchParam=<params>`,
+or `SYNO.SDS.AppLaunch('SYNO.SDS.<package>.Instance', {route: '/a/notes/42'})`
+from DSM's own JavaScript. The DSM window passes the
+App's string values from the launch that opened it as `ctx.launchParams`, and
+those of each later launch of the open window to `ctx.onLaunch(fn)`. The
+values are untrusted text.
+
+`route` is the convention the helpers read: the App route a portal link puts
+after its `#`. `launchRoute(params)` returns it when it is a path from the App
+root (one leading `/`, no backslash or control character, at most 2048
+characters), else `undefined`. `followLaunchRoute(ctx, navigate)` navigates to
+the opening launch's route at once and to each later one's, and returns a
+function that stops; outside DSM it follows nothing. Map both sources onto the
+same router: a portal or full-page launch reads its own `#` as before.
+
+```ts
+// Vue Router with createWebHashHistory: #/a/notes/42 in a portal link, route=/a/notes/42 from DSM.
+const stop = followLaunchRoute(ctx, route => { void router.replace(route) })
+```
+
+`dsmLaunchURL(origin, packageId, params)` builds the desktop link, encoding each
+key and value the way DSM decodes them:
+
+```ts
+dsmLaunchURL('https://nas.example:5001', 'HelloGo', {route: '/a/notes/42'})
+// https://nas.example:5001/?launchApp=SYNO.SDS.HelloGo.Instance&launchParam=route%3D%252Fa%252Fnotes%252F42
+```
+
+DSM replays the opening launch's values when it restores the desktop's windows
+at sign-in, so a restored window opens on the same page.
+
 ## Outside DSM
 
 A development page, a preview or a test owns the browser page and has no DSM