Improve documentation for how to use the embedded package (#3146)

Author: hughns

docs/embedded-standalone.md

@@ -1,6 +1,10 @@
 ## Element Call packages
 
-Element Call is available as two different packages: Full Package and Embedded Package. The Full Package is designed for standalone use, while the Embedded Package is designed for widget mode only. The table below provides a comparison of the two packages:
+Element Call is available as two different packages: Full Package and Embedded Package.
+
+The Full Package is designed for standalone use, while the Embedded Package is designed for widget mode only.
+
+The table below provides a comparison of the two packages:
 
 |                                              | Full Package                                                                                                                      | Embedded Package                                                                                                                                                                                                    |
 | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -13,8 +17,16 @@ Element Call is available as two different packages: Full Package and Embedded P
 | **Analytics consent**                        | Element Call will show a consent UI.                                                                                              | Element Call will not show a consent UI. The messenger app should only provide the embedded Element Call with the [analytics URL parameters](./url-params.md#embedded-only-parameters) if consent has been granted. |
 | **Analytics data**                           | Element Call will send data to the Posthog, Sentry and Open Telemetry targets specified by the administrator in the `config.json` | Element Call will send data to the Posthog and Sentry targets specified in the URL parameters by the messenger app                                                                                                  |
 
-For examples of how to use the platform specific release artifacts (e.g. Android AAR) see
-the Element Messenger apps for: [Web](https://github.com/element-hq/element-web), [iOS](https://github.com/element-hq/element-x-ios) and [Android](https://github.com/element-hq/element-x-android).
+### Using the embedded package within a messenger app
+
+Currently the best way to understand the necessary steps is to look at the implementations in the Element Messenger apps: [Web](https://github.com/element-hq/element-web/pull/29309), [iOS](https://github.com/element-hq/element-x-ios/pull/3939) and [Android](https://github.com/element-hq/element-x-android/pull/4470).
+
+The basics are:
+
+1. Add the appropriate platform dependency as given for a [release](https://github.com/element-hq/element-call/releases), or use the embedded tarball. e.g. `npm install @element-hq/[email protected]`
+2. Include the assets from the platform dependency in the build process. e.g. copy the assets during a [Webpack](https://github.com/element-hq/element-web/blob/247cd8d56d832d006d7dfb919d1042529d712b59/webpack.config.js#L677-L682) build.
+3. Use the `index.html` entrypointof the imported assets when you are constructing the WebView or iframe. e.g. using a [relative path in a webapp](https://github.com/element-hq/element-web/blob/247cd8d56d832d006d7dfb919d1042529d712b59/src/models/Call.ts#L680), or on the the Android [WebViewAssetLoader](https://github.com/element-hq/element-x-android/blob/fe5aab6588ecdcf9354a3bfbd9e97c1b31175a8f/features/call/impl/src/main/kotlin/io/element/android/features/call/impl/utils/DefaultCallWidgetProvider.kt#L20)
+4. Set any of the [embedded-only URL parameters](./url-params.md#embedded-only-parameters) that you need.
 
 ## Widget vs standalone mode