Skip to main content

Using Portals in Android

Once you obtain an API key and install Ionic Portals, you can start creating Portals for your application.

Creating a Custom Application Class

In Android, you will have to register your Portals instance and start creating Portals via the PortalManager. To do this, a custom Application class is recommended. In this Application class, you can override Application#onCreate() to register and create Portals.

MyApplication.kt
class MyApplication : Application() {
    override fun onCreate(): Unit {
        super.onCreate()
        PortalManager.register("YOUR_PORTALS_KEY")
        // setup portals
    }
}
caution

Avoid committing your Portals key to source code repositories where it may be publicly visible! On Android, you can use the Secrets Gradle Plugin to keep it out of a public repository.

After creating a custom Application class, be sure to add the android:name attribute to your application tag in the AndroidManifest.xml.

AndroidManifest.xml
<?xml version="1.0" encoding="utf-8"?>
<manifest
    xmlns:android="http://schemas.android.com/apk/res/android"
    package="org.example.my.app">

    <application
        android:name=".MyApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name">
        /* ... */
        /* other manifest code here */
        /* ... */
    </application>
</manifest>

Creating a Portal via PortalManager

After registering via the PortalManager.register() function, you can create Portals. Use the PortalManager to quickly create a Portal and link it to an XML layout.

class MyApplication : Application() {
    override fun onCreate(): Unit {
        super.onCreate()
        PortalManager.register("YOUR_PORTALS_KEY")

        val portalId = "MY_FIRST_PORTAL"
        PortalManager.newPortal(portalId).create()
    }
}

Now, the Portal is successfully created and managed by the PortalManager.

Linking the Portal in a Layout File

One way to use Portals in android is directly in an XML layout file. Use the portalId attribute in the XML tag as shown below to link it to the Portal you created.

<?xml version="1.0" encoding="utf-8"?>
<io.ionic.portals.PortalView
    app:portalId="MY_FIRST_PORTAL"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
/>

The strings.xml resources file can be used to ensure the Portal ids match up, but it isn't necessary to do so.

Using a Portal in Code

Another way to use Portals in Android is to inflate a PortalFragment with a Portal into a view. This method may be preferred if using a Portal in a ViewPager or a more dynamic UI structure. The following trivial example shows how to inflate a PortalFragment into an existing FrameLayout.

fragment_container.xml
<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <FrameLayout
        android:id="@+id/my_portal_space"
        android:layout_width="match_parent"
        android:layout_height="match_parent"/>

</RelativeLayout>
class MyContainerFragment : Fragment() {

    override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View? {
        return inflater.inflate(R.layout.fragment_container, container, false)
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val myFirstPortal = getPortal("MY_FIRST_PORTAL")
        val portalFragment = PortalFragment(myFirstPortal)

        val fragmentManager: FragmentManager = childFragmentManager
        fragmentManager.beginTransaction().replace(R.id.my_portal_space, portalFragment).commit()
    }
}

Jetpack Compose

Portals can be used with Jetpack Compose. Make sure that Activities containing Portals extend AppCompatActivity() so that the AppCompat Fragment APIs are available to them.

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            MyThemeName {
                Surface(
                    modifier = Modifier.fillMaxSize()
                ) {
                    loadPortal("myPortalName")
                }
            }
        }
    }
}

@Composable
fun loadPortal(portalId: String) {
    AndroidView(factory = {
        PortalView(it, portalId)
    })
}
note

Jetpack Compose support is new. If you encounter any issues, please open an issue in our repository.

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.

android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode"

For example:

<activity
    android:name=".MainActivity"
    android:label="MyExampleApp"
    android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
</activity>

Preparing the Gradle Build File

Some web assets can contain directories that start with special characters like an underscore, but by default Android will omit these from your built app. Override the default Android settings by adding the following snippet in the defaultConfig section of your module build.gradle file.

aaptOptions {
    // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
    // Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61
    ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
}

For example:

android {
    compileSdkVersion rootProject.ext.compileSdkVersion
    defaultConfig {
        applicationId "com.myawesomecompany"
        minSdkVersion rootProject.ext.minSdkVersion
        targetSdkVersion rootProject.ext.targetSdkVersion
        versionCode 1
        versionName "1.0"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
        aaptOptions {
             // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
             // Default: https://android.googlesource.com/platform/frameworks/base/+/282e181b58cf72b6ca770dc7ca5f91f135444502/tools/aapt/AaptAssets.cpp#61
            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
        }
    }

    ...
}

Adding Web Code

Now that your Portal is successfully registered, created, and linked, you need to add the web assets to your application. The web code lives in folders under src/main/assets. You can use either many web applications or one "Single Page Application" (SPA) and dynamically link to the route you want to use. By default, the PortalManager will look in the folder named the same as the portalId used. You can use the setStartDir() function to set the web application's directory.

For more information on how to setup your web bundle, see our how-to guide on how to pull in a web bundle.