fix(howto): polish exchange-oob-data page #223

adglkh · 2024-11-19T03:13:04Z

Provide a complete howto guide for the integration of out-of-band v2
feature into the Android application.

keirthana

Some minor suggestions and one question.

howto/stream/exchange-oob-data.md

Provide a complete howto guide for the integration of out-of-band v2 feature into the Android application.

keirthana

LGTM

adglkh · 2024-11-20T05:34:37Z

@morphis will you take another look at this in case something I am missing ?
Thanks

morphis · 2024-11-20T07:20:19Z

@adglkh yes, I wanted to look at this. I will leave comments here next

morphis · 2024-11-20T07:20:52Z

@adglkh btw. you can set specific people as reviewer when you want their explicit review before things can be merged.

morphis

We're moving forward but I think we still have to rework this further as there are still too many obstacles in the way to let people have a smooth journey with this how-to.

Next to inline comments a few more:

We should not talk about the "Anbox WebRTC platform" but about the "Anbox runtime". That's simpler for people to understand.
In the "Anbox WebRTC platform" it is unclear how that relates to the former "Prepare your web application" section. We should give a clear set of steps on how someone can test that their now changed web application can exchange messages with the Anbox instance over socat

Overall I think we're too vague and not following a clear sequence in this how-to yet. People should get everything needed to follow the how-to without having to read a lot more sections in our documentation or start writing a lot of code themselves with potentially a lot more obstacles.

A couple of suggestions:

When we want them to test the Android side, let them use the existing example application we have but instead of just let them install, highlight important parts of the example application. In the end they can either compile the app and do modifications or just use the prebuilt APK to get a head start without a lot work.
The same applies for the web client. We should show changes necessary relative to the streaming tutorial so we have consistency and allow people to easily follow.
If we say "Confirm that..." or similar we need to tell them how to do that. Otherwise people will be confused and either don't complete that step or reach out and ask for clarifications.

morphis · 2024-11-20T07:22:36Z

howto/stream/exchange-oob-data.md

@@ -23,6 +24,8 @@ The following instructions guide you to exchange OOB data using a specific imple

 The following instructions will walk you through how to set up data channels and perform data transmission in both directions between an Android application and a WebRTC platform.

+Before proceeding, ensure that you have set up a web-based streaming client using the Anbox Cloud streaming stack. If you haven't done so, please follow our setup [guide](https://documentation.ubuntu.com/anbox-cloud/en/latest/tutorial/stream-client/).
+
 ### Prepare your web application


We should make the code changes below based on top of what the streaming tutorial has as an example so it's simple for people to apply. Currently it's unclear for example where stream.sendData should be put.

We should also point that out beforehand that we base all example code on top of this.

morphis · 2024-11-20T07:26:42Z

howto/stream/exchange-oob-data.md

@@ -159,6 +158,10 @@ public class DataChannelEventReceiver extends BroadcastReceiver {
 }
 ```

+```{note}
+If an instance is running on Android 14 image, enabling the out-of-band v2 feature requires the Android app to be running in order to receive broadcasts. If the app is in the [cached state](https://developer.android.com/guide/components/activities/process-lifecycle), the system places [context-registered broadcasts in a queue]((https://developer.android.com/develop/background-work/background-tasks/broadcasts#android-14)),meaning the app may not receive broadcasts immediately, as it would when the app is actively running.
+```


What is needed for a user to do to achieve this? It's not clear to me how I can fix this without having a deep understanding of what Android does / can be influenced

Let me reword this a bit

morphis · 2024-11-20T07:29:06Z

howto/stream/exchange-oob-data.md

+
+To connect the data channel to the Anbox WebRTC data proxy service within an Android container, the Android app must be installed and running as a system app. To do so, proceed with the following steps:
+1. Add the attribute `android:sharedUserId="android.uid.system"` into the `<manifest>` tag in the `AndroidManifest.xml` file of your Android app
+2. Create an addon to install your APK as a system app through the pre-start hook with the following content:


Why can't we use a raw instance instead? Adding the need for addons IMHO just makes things complicated here.

That's a good idea.

Hmm, no, we can't. Using the raw instance makes it impossible to run a pre-start hook where the APK is going to be installed as a system app. I suppose what you meant above was to use the application hooks, but that makes no difference to me. The example below already uses the raw instance.

morphis · 2024-11-20T07:30:12Z

howto/stream/exchange-oob-data.md

+
+   See [How to install an APK as a system app](https://documentation.ubuntu.com/anbox-cloud/en/latest/howto/port/install-apk-system-app/#howto-install-apk-system-app) for details.
+
+3. Navigate to the addon directory and add it to AMS:


If people just blindly follow the above (and they will do) they will fail as the manifest.yaml is missing, the hook is maybe not executable etc. If we give steps, they should work and include everything needed to succeed

I think that's too much detail for this context. By this point, people should already know how to create an addon and, further, how to install an APK as a system app.

morphis · 2024-11-20T07:30:34Z

howto/stream/exchange-oob-data.md

+Once the session is active:
+
+1. Use the web client, which creates a custom data channel `foo` to initiate the WebRTC connection.
+2. After the WebRTC connection is established, verify that the Android application receives a notification indicating the availability of the `foo` data channel.


How do I do this?

morphis · 2024-11-20T07:30:43Z

howto/stream/exchange-oob-data.md

+
+1. Use the web client, which creates a custom data channel `foo` to initiate the WebRTC connection.
+2. After the WebRTC connection is established, verify that the Android application receives a notification indicating the availability of the `foo` data channel.
+3. Confirm that the Android application can connect to the `foo` data channel created by the web client.


How do I do that?

morphis · 2024-11-20T07:30:52Z

howto/stream/exchange-oob-data.md

+1. Use the web client, which creates a custom data channel `foo` to initiate the WebRTC connection.
+2. After the WebRTC connection is established, verify that the Android application receives a notification indicating the availability of the `foo` data channel.
+3. Confirm that the Android application can connect to the `foo` data channel created by the web client.
+4. Send messages from either the Android application or the WebRTC client, and ensure that the messages are successfully sent and and received over the `foo` data channel.


How do I do that?

keirthana · 2024-11-20T07:53:20Z

howto/stream/exchange-oob-data.md

+
+#### Run end-to-end test
+
+To launch a streamable instance with the addon you created, run:


Sorry, I know I suggested this earlier but stream-enabled is better instead of streamable (Spellcheck also does not recognise streamable).

Sure, let me change that.

Ah, you've done that. :)
Thanks

adglkh · 2024-11-21T02:58:07Z

We're moving forward but I think we still have to rework this further as there are still too many obstacles in the way to let people have a smooth journey with this how-to.

Next to inline comments a few more:

We should not talk about the "Anbox WebRTC platform" but about the "Anbox runtime". That's simpler for people to understand.

In the "Anbox WebRTC platform" it is unclear how that relates to the former "Prepare your web application" section. We should give a clear set of steps on how someone can test that their now changed web application can exchange messages with the Anbox instance over socat

Overall I think we're too vague and not following a clear sequence in this how-to yet. People should get everything needed to follow the how-to without having to read a lot more sections in our documentation or start writing a lot of code themselves with potentially a lot more obstacles.

A couple of suggestions:

When we want them to test the Android side, let them use the existing example application we have but instead of just let them install, highlight important parts of the example application. In the end they can either compile the app and do modifications or just use the prebuilt APK to get a head start without a lot work.

The same applies for the web client. We should show changes necessary relative to the streaming tutorial so we have consistency and allow people to easily follow.

If we say "Confirm that..." or similar we need to tell them how to do that. Otherwise people will be confused and either don't complete that step or reach out and ask for clarifications.

Thanks for the detailed review; I missed this yesterday.

I understand the concerns about the current documentation's usability. While there is a balance between providing sufficient detail for developers and simplifying the process for those who are new to the concepts, it ultimately depends on the targeted audience. This document assumes that the reader has some background in Android development and WebRTC when hands on this feature integration. If the targeted audience is the developer, they don't want to dive too much details which is something out of the feature itself. That would also answer those questions about How do I do that. This is also how the Android sample does today. (There are more under https://github.com/android )

https://github.com/android/user-interface-samples/tree/main/DownloadableFonts/
https://github.com/android/connectivity-samples/tree/main/BluetoothAdvertisements

I agree that the learning path for newcomers to this feature is not as friendly as it could be, and a bit challenging too . Regarding the comment, 'Overall, I think we're too vague and not following a clear sequence in this how-to yet,' I would suggest following the approach used by Android and providing a complete step-by-step how-to guide that walks the reader through the process to achieve the goal instead of linking a different source(E.g. stream client and modify by themselves) and pieced them together as a final technical doc.

Create your first Android app
[Jetpack Compose basics]https://developer.android.com/codelabs/jetpack-compose-basics#0

When we want them to test the Android side, let them use the existing example application we have but instead of just let them install, highlight important parts of the example application. In the end they can either compile the app and do modifications or just use the prebuilt APK to get a head start without a lot work.
A: +1
The same applies for the web client. We should show changes necessary relative to the streaming tutorial so we have consistency and allow people to easily follow.
A: +1

keirthana · 2024-11-21T05:05:21Z

I understand the concerns about the current documentation's usability. While there is a balance between providing sufficient detail for developers and simplifying the process for those who are new to the concepts, it ultimately depends on the targeted audience. This document assumes that the reader has some background in Android development and WebRTC when hands on this feature integration. If the targeted audience is the developer, they don't want to dive too much details which is something out of the feature itself.

@adglkh I can have a working meeting with you early next week to figure this out. We can create a single how-to guide not assuming any knowledge from the user, but if that would be too much detail for an expert audience, we could also create two sections with clear delineation of what applies to whom.

(Also, sorry that I assumed the technical review part of it and merged this early. So we have to open another PR for the changes Simon has suggested. I will ensure one doc reviewer and one tech reviewer approval from going forward.)

adglkh · 2024-11-21T05:22:19Z

@adglkh I can have a working meeting with you early next week to figure this out. We can create a

A: yes, let's meet up next week for this. I can resolve all of the existing review comments that Simon left above as most of them makes sense to me.

Polish the out-of-band-v2 chapter and to resolve the comments in the canonical#223 PR

adglkh requested a review from a team as a code owner November 19, 2024 03:13

adglkh mentioned this pull request Nov 19, 2024

Polish out-of-band v2 example application canonical/anbox-streaming-sdk#88

Merged

keirthana requested changes Nov 19, 2024

View reviewed changes

fix(howto): polish exchange-oob-data page

a2282f0

Provide a complete howto guide for the integration of out-of-band v2 feature into the Android application.

adglkh force-pushed the polish_out_of_band_v2 branch from 84e42dd to a2282f0 Compare November 20, 2024 04:44

keirthana approved these changes Nov 20, 2024

View reviewed changes

keirthana merged commit 6daac36 into canonical:main Nov 20, 2024
2 of 3 checks passed

morphis reviewed Nov 20, 2024

View reviewed changes

keirthana reviewed Nov 20, 2024

View reviewed changes

adglkh added a commit to adglkh/anbox-cloud-docs that referenced this pull request Nov 21, 2024

feat(exchange-oob-data): polish the out-of-band-v2 chapter

6c80251

Polish the out-of-band-v2 chapter and to resolve the comments in the canonical#223 PR

adglkh mentioned this pull request Nov 21, 2024

feat(oobv2): polish the out-of-band-v2 chapter #228

Merged

adglkh added a commit to adglkh/anbox-cloud-docs that referenced this pull request Nov 22, 2024

feat(exchange-oob-data): polish the out-of-band-v2 chapter

0da970e

Polish the out-of-band-v2 chapter and to resolve the comments in the canonical#223 PR

adglkh added a commit to adglkh/anbox-cloud-docs that referenced this pull request Nov 25, 2024

feat(exchange-oob-data): polish the out-of-band-v2 chapter

17ef261

Polish the out-of-band-v2 chapter and to resolve the comments in the canonical#223 PR

adglkh added a commit to adglkh/anbox-cloud-docs that referenced this pull request Nov 26, 2024

feat(exchange-oob-data): polish the out-of-band-v2 chapter

4cc9ee8

Polish the out-of-band-v2 chapter and to resolve the comments in the canonical#223 PR

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(howto): polish exchange-oob-data page #223

fix(howto): polish exchange-oob-data page #223

adglkh commented Nov 19, 2024

keirthana left a comment

keirthana left a comment

adglkh commented Nov 20, 2024

morphis commented Nov 20, 2024

morphis commented Nov 20, 2024

morphis left a comment

morphis Nov 20, 2024

morphis Nov 20, 2024

adglkh Nov 21, 2024

morphis Nov 20, 2024

adglkh Nov 21, 2024

morphis Nov 20, 2024

adglkh Nov 21, 2024

adglkh Nov 21, 2024

morphis Nov 20, 2024

adglkh Nov 21, 2024

morphis Nov 20, 2024

morphis Nov 20, 2024

morphis Nov 20, 2024

keirthana Nov 20, 2024

adglkh Nov 21, 2024

adglkh Nov 21, 2024

adglkh commented Nov 21, 2024

keirthana commented Nov 21, 2024

adglkh commented Nov 21, 2024


		See [How to install an APK as a system app](https://documentation.ubuntu.com/anbox-cloud/en/latest/howto/port/install-apk-system-app/#howto-install-apk-system-app) for details.

		3. Navigate to the addon directory and add it to AMS:


		#### Run end-to-end test

		To launch a streamable instance with the addon you created, run:

fix(howto): polish exchange-oob-data page #223

fix(howto): polish exchange-oob-data page #223

Conversation

adglkh commented Nov 19, 2024

keirthana left a comment

Choose a reason for hiding this comment

keirthana left a comment

Choose a reason for hiding this comment

adglkh commented Nov 20, 2024

morphis commented Nov 20, 2024

morphis commented Nov 20, 2024

morphis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

adglkh commented Nov 21, 2024

keirthana commented Nov 21, 2024

adglkh commented Nov 21, 2024