docs(android): added section for using PortalBuilder directly and not…

…e the difference (#250)

website/docs/for-android/getting-started.md

@@ -10,7 +10,7 @@ Once you [obtain an API key](./guide#signup) and [install Ionic Portals](./guide
 
 ## Creating a Custom Application Class
 
-In Android, you will have to register your Portals instance and start creating Portals via the [PortalManager](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html). To do this, a custom [Application](https://developer.android.com/reference/android/app/Application) class is recommended. In this Application class, you can override `Application#onCreate()` to register and create Portals.
+In Android, you will have to register your Portals instance via the [PortalManager](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html). To do this, a custom [Application](https://developer.android.com/reference/android/app/Application) class is recommended. In this Application class, you can override `Application#onCreate()` to register and create Portals. We recommend placing this register call inside the custom `Application` class so that it is handled immediately when your app is launched, but you can place it anywhere in an app as long as it is called before any Portals are loaded.
 
 <Tabs
 defaultValue="kt"
@@ -74,6 +74,8 @@ After creating a custom Application class, be sure to add the `android:name` att
 
 ## Creating a Portal via PortalManager
 
+The [PortalManager](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html) provides convenience functions to handle the storing and retrieving of information about Portals used in your app. When using it, we recommend creating your portals in the custom `Application` class in the same place where Portals is registered so that all the required information for Portals to function is available immediately to the SDK every time the app is launched. If you prefer to have more granular control over the creation and storing of Portals data, and where it occurs in your app, we recommend creating Portals using the [PortalBuilder](./getting-started#creating-a-portal-via-portalbuilder).
+
 After registering via the [PortalManager.register()](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html#-1847662668%2FFunctions%2F-149544105) function, you can create Portals. Use the [PortalManager](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html) to quickly create a [Portal](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html) and link it to an XML layout.
 
 <Tabs
@@ -243,6 +245,82 @@ fun loadPortal(portalId: String) {
 Jetpack Compose support is new. If you encounter any issues, please [open an issue](https://github.com/ionic-team/ionic-portals-android) in our repository.
 :::
 
+## Creating a Portal via PortalBuilder
+
+The [PortalBuilder](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-builder/index.html) provides a way to create Portal objects without relying on the `PortalManager` class convenience functions. This might be useful if you want to use Portals in a custom library, or need a more advanced way to have granular control around how Portals works with your applicaion lifecycle.
+
+Create a Portal in your app code using `PortalBuilder`:
+
+<Tabs
+defaultValue="kt"
+values={[
+{ label: 'Kotlin', value: 'kt', },
+{ label: 'Java', value: 'java', },
+]}>
+<TabItem value="kt">
+
+```kotlin
+val portal: Portal = PortalBuilder("myPortal")
+    .addPlugin(MyCapacitorPlugin::class.java)
+    .setPortalFragmentType(MyFadeInOutPortalFragment::class.java)
+    .setInitialContext(mapOf("myVariableFromAndroid" to 42))
+    .setStartDir("web_app")
+    .create()
+```
+
+</TabItem>
+<TabItem value="java">
+
+```java
+Portal portal = new PortalBuilder("myPortal")
+    .addPlugin(MyCapacitorPlugin.class)
+    .setPortalFragmentType(MyFadeInOutPortalFragment.class)
+    .setInitialContext(Map.of("myVariableFromAndroid", 42))
+    .setStartDir("web_app")
+    .create();
+```
+
+</TabItem>
+</Tabs>
+
+Once created, you may use your Portal object to create views:
+
+<Tabs
+defaultValue="kt"
+values={[
+{ label: 'Kotlin', value: 'kt', },
+{ label: 'Java', value: 'java', },
+]}>
+<TabItem value="kt">
+
+```kotlin
+// Make a PortalFragment with your Portal
+val myPortalFragment = PortalFragment(portal)
+
+// Make a PortalView with your Portal
+val myPortalView = PortalView(context, portal)
+```
+
+</TabItem>
+<TabItem value="java">
+
+```java
+// Make a PortalFragment with your Portal
+PortalFragment myPortalFragment = new PortalFragment(portal);
+
+// Make a PortalView with your Portal
+PortalView myPortalView = new PortalView(context, portal);
+```
+
+</TabItem>
+</Tabs>
+
+Since the `PortalManager` is not used with these objects, make sure to retain them to be used in a way that suits your needs.
+
+:::warning
+Do not retain **view** objects such as `PortalView` or `PortalFragment` outside of the Activity lifecycle.
+:::
+
 ## Preparing the Containing Activity
 
 Configuration changes in Android can cause WebViews to restart within an Activity. We recommend adding the following line of code in your application `AndroidManifest.xml` file for any Activity that will contain a Portal.

website/docs/for-android/guide.md

@@ -66,7 +66,9 @@ If you need help configuring specific versions of Portals with Capacitor or Capa
 
 ## Configure
 
-After installing the dependency you need to register your copy of Ionic Portals at runtime. This works both offline and in production. You'll need to call [PortalManager.register(myApiKey)](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html#-1847662668%2FFunctions%2F-149544105) before creating any Portals in your app. Below is a simple example of how to bootstrap Ionic Portals before loading any Portal instances in your app. To get an API Key, refer to the [Sign Up](#signup) section.
+After installing the dependency you need to register your copy of Ionic Portals at runtime. This works both offline and in production. You'll need to call [PortalManager.register(myApiKey)](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html#-1847662668%2FFunctions%2F-149544105) before creating any Portals in your app. To get an API Key, refer to the [Sign Up](#signup) section.
+
+Below is a simple example of how to bootstrap Ionic Portals before loading any Portal instances in your app. We recommend placing this register call inside the `onCreate()` function of a custom `Application` class so that it is handled immediately when your app is launched, but you can place it anywhere as long as it is called before your app tries to load any Portals.
 
 ```kotlin title=MyApplication.kt
 import android.app.Application

website/docs/for-android/quick-start.md

@@ -273,7 +273,7 @@ dependencies {
 
 After installation of Portals we can setup the Portals key. Then the application is ready to have its first Portal configured. To do this, a custom [Application](https://developer.android.com/reference/android/app/Application) class is recommended. In this Application class, you can override `Application#onCreate()` to register and create Portals. 
 
-You'll need to call [PortalManager.register(myApiKey)](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html#-1847662668%2FFunctions%2F-149544105) before creating any Portals in your app. Below is a simple example of how to bootstrap Ionic Portals before loading any Portal instances in your app. To get an API Key, refer to the [Sign Up](#signup) section.
+You'll need to call [PortalManager.register(myApiKey)](https://ionic.io/docs/portals-android-api-ref/-ionic-portals/io.ionic.portals/-portal-manager/index.html#-1847662668%2FFunctions%2F-149544105) before creating any Portals in your app. Below is a simple example of how to bootstrap Ionic Portals before loading any Portal instances in your app. Putting this registration call in an `Application` class is a good way to guarantee it is called before any Portals are created, but you can call it anywhere in your app as long as it happens before Portals are loaded. To get an API Key, refer to the [Sign Up](#signup) section.
 
 <Tabs
 defaultValue="kt"