From 18b2fca397ce7593a4e06ac20ee64bbd001ad321 Mon Sep 17 00:00:00 2001
From: Damien Arrachequesne <damien.arrachequesne@gmail.com>
Date: Mon, 4 Jul 2022 02:37:51 +0200
Subject: [PATCH] docs: init Android documentation

Related:

- https://github.com/socketio/socket.io-client-java/issues/606
- https://github.com/socketio/socket.io-client-java/issues/435
---
 src/site/markdown/android.md | 59 ++++++++++++++++++++++++++++++++++++
 src/site/site.xml            |  1 +
 2 files changed, 60 insertions(+)
 create mode 100644 src/site/markdown/android.md

diff --git a/src/site/markdown/android.md b/src/site/markdown/android.md
new file mode 100644
index 0000000..a33b2f9
--- /dev/null
+++ b/src/site/markdown/android.md
@@ -0,0 +1,59 @@
+# Android
+
+<!-- MACRO{toc} -->
+
+## How to keep a Socket.IO client running in the background?
+
+Long story short, you probably shouldn't. The Socket.IO client is not meant to be used in a [background service](https://developer.android.com/guide/components/services?hl=en), as it will keep an open TCP connection to the server and quickly drain the battery of your users.
+
+It is totally usable in the foreground though.
+
+See also: https://developer.android.com/training/connectivity
+
+## How to reach an HTTP server?
+
+Starting with Android 9 (API level 28) you need to explicitly allow cleartext traffic to be able to reach an HTTP server (e.g. a local server at `http://192.168.0.10`):
+
+- either for all domains:
+
+`app/src/main/AndroidManifest.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<manifest>
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application android:usesCleartextTraffic="true">
+        ...
+    </application>
+</manifest>
+```
+
+- or for a restricted list of domains:
+
+`app/src/main/AndroidManifest.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<manifest>
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application android:networkSecurityConfig="@xml/network_security_config">
+        ...
+    </application>
+</manifest>
+```
+
+`app/src/main/res/xml/network_security_config.xml`
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<network-security-config>
+    <domain-config cleartextTrafficPermitted="true">
+        <domain includeSubdomains="true">localhost</domain>
+        <domain includeSubdomains="true">192.168.0.10</domain>
+    </domain-config>
+</network-security-config>
+```
+
+Reference: https://developer.android.com/training/articles/security-config
diff --git a/src/site/site.xml b/src/site/site.xml
index 5ffff49..ef9fa82 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -31,6 +31,7 @@
             <item name="The Socket instance" href="./socket_instance.html"/>
             <item name="Migrating from 1.x" href="./migrating_from_1_x.html"/>
             <item name="FAQ" href="./faq.html"/>
+            <item name="Android" href="./android.html"/>
         </menu>
 
         <menu name="Miscellaneous">