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.

Kotlin

MyApplication.kt

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

Java

MyApplication.java

public class MyApplication extends Application {    @Override    public void onCreate() {        super.onCreate();        PortalManager.register("MY_API_KEY");        // setup portals    }}

caution

Avoid committing your Portals key to source code repositories where it may be publicly visible!

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.

Kotlin

class MyApplication : Application() {    override fun onCreate(): Unit {        super.onCreate()        PortalManager.register("MY_API_KEY")
        val portalId = "MY_FIRST_PORTAL"        PortalManager.newPortal(portalId).create()    }}

Java

public class MyApplication extends Application {    @Override    public void onCreate() {        super.onCreate();        PortalManager.register("MY_API_KEY");
        String 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>

Kotlin

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()    }}

Java

public class MyContainerFragment extends Fragment {
    @Override    public View onCreateView(@NonNull @NotNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) {        return inflater.inflate(R.layout.fragment_container, container, false);    }
    @Override    public void onCreate(@Nullable Bundle savedInstanceState) {        super.onCreate(savedInstanceState);
        Portal myFirstPortal = PortalManager.getPortal("MY_FIRST_PORTAL");        PortalFragment portalFragment = new PortalFragment(myFirstPortal);
        final FragmentManager fragmentManager = getChildFragmentManager();        fragmentManager.beginTransaction().replace(R.id.my_portal_space, portalFragment).commit();    }}

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>

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.