How to Communicate with a Portal Web Application

The PortalsPlugin provides useful features to aid in communication between your Web and Native applications. It is included in the Ionic Portals library by default and takes advantage of the Capacitor Plugin system.

Setup

Android

Follow the Getting Started Guide to install the Ionic Portals library into your native mobile projects. The PortalsPlugin is automatically added to every instance of a Portal.

Web

Install the Ionic Portals package from NPM into your web application.

npm install @ionic/portals

Initial Context

The Initial Context mechanism allows you to pass data to your web application from native so that it is available for when the web application initially loads.

Setting Initial Context

Initial context data can be set in two different ways. You may want to set it when building a new Portal using PortalManager.

Kotlin

PortalManager.newPortal("maps")
    .setStartDir("web")
    .setInitialContext(mapOf("ic_example" to "hello world"))
    .create()

Java

PortalManager.newPortal("maps")
    .setStartDir("web")
    .setInitialContext(Map.of("ic_example", "hello world"))
    .create();

You can also set Initial Context data on a Portal object prior to the Portal loading.

Kotlin

val mapsPortal = PortalManager.getPortal("maps")
mapsPortal?.setInitialContext(mapOf("ic_example" to "hello world"))

Java

Portal mapsPortal = PortalManager.getPortal("maps");
mapsPortal.setInitialContext(Map.of("ic_example", "hello world"));

Using Initial Context

To access the initial context set from the native application in your web application, import getInitialContext from @ionic/portals use the getInitialContext() function.

import { getInitialContext } from "@ionic/portals";

const initialContext = getInitialContext<{ ic_example: string }>();
// prints "hello world" in this example
console.log(initialContext?.value?.ic_example);

Initial context is useful when using a Single Page Application (SPA) across multiple Portals in your application. The route to a specific section of the SPA can be passed in as initial context data. Your web application can then use it to load that section directly without need for a redirect. Check out our how-to guide.

Communicating via Pub/Sub

The Publish and Subscribe mechanism (pub/sub) built into the PortalsPlugin allows you to send data between your web and native applications through a Portal.

Defining Subscribers

Subscribers listen for messages sent to a certain topic. They can be defined in your web application to listen for messages published from native, and vice versa.

To listen for a message published from the native side of a Portal, define a subscriber in your web application.

const portalSubscription = await Portals.subscribe({ topic }, (result) => {
  console.log(JSON.stringify(result));
});

To listen for messages published from the web side of a Portal, define a subscriber in your native application.

Kotlin

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

    // ...

    val portal = PortalManager.getPortal("example")
    val portalFragment = PortalFragment(portal)

    // listen on the topic "dismiss" and act on the result data.
    // This is an example to dismiss a containing native DialogFragment.
    PortalsPlugin.subscribe("dismiss") { result ->
        if (result.data == "cancel" || result.data == "success") {
            this.dismiss()
        }
    }

    // ...

    // add the PortalFragment to the example container fragment
    val fragmentManager = childFragmentManager
    fragmentManager.beginTransaction().replace(R.id.example_web_app, portalFragment!!).commit()
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // ...

    Portal portal = PortalManager.getPortal("example");
    PortalFragment portalFragment = new FadePortalFragment(portal);

    // listen on the topic "dismiss" and act on the result data.
    // This is an example to dismiss a containing native DialogFragment.
    PortalsPlugin.subscribe("dismiss", (subscriptionResult -> {
        if(subscriptionResult.getData().equals("cancel")
            || subscriptionResult.getData().equals("success")) {

            this.dismiss();
        }

        return Unit.INSTANCE;
    }));

    // ...

    // add the PortalFragment to the example container fragment
    final FragmentManager fragmentManager = getChildFragmentManager();
    fragmentManager.beginTransaction().replace(R.id.example_web_app, portalFragment).commit();
}

Subscribe Using Annotations

Android also provides a way to link subscribers defined as methods with annotations.

Kotlin

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

    // ...

    val portal = PortalManager.getPortal("example")
    val portalFragment = PortalFragment(portal)

    // register this class as having defined message subscribers
    portalFragment!!.linkMessageReceivers(this)

    // ...

    // add the PortalFragment to the example container fragment
    val fragmentManager = childFragmentManager
    fragmentManager.beginTransaction().replace(R.id.example_web_app, portalFragment!!).commit()
}

/**
 * Define a `dismiss` method to receive messages on the "dismiss"
 * topic and act on the message. This is an example to dismiss
 * a containing native DialogFragment.
 */
@PortalMethod
fun dismiss(result: String?) {
    if (result != null && (result == "cancel" || result == "success")) {
        this.dismiss()
    }
}

Java

@Override
public void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    // ...

    Portal portal = PortalManager.getPortal("example");
    PortalFragment portalFragment = new FadePortalFragment(portal);

    // register this class as having defined message subscribers
    portalFragment.linkMessageReceivers(this);

    // ...

    // add the PortalFragment to the example container fragment
    final FragmentManager fragmentManager = getChildFragmentManager();
    fragmentManager.beginTransaction().replace(R.id.example_web_app, portalFragment).commit();
}

/**
 * Define a `dismiss` method to receive messages on the "dismiss"
 * topic and act on the message. This is an example to dismiss
 * a containing native DialogFragment.
 */
@PortalMethod
public void dismiss(String result) {
    if(result != null && (result.equals("cancel") || result.equals("success"))) {
        this.dismiss();
    }
}

Publishing Messages

Publish messages to send data through a Portal to registered Subscribers.

From Web to iOS/Android

To send a message from your web application to iOS or Android, use the Portals.publish() function.

Portals.publish({ topic: "dismiss", data: "success" });

From Android to Web

To send messages from your native application to the web application, use the PortalsPlugin.publish() methods.

Kotlin

PortalsPlugin.publish("weather", "sunny")

Java

PortalsPlugin.publish("weather", "sunny");

Examples

The PortalsPlugin is used in the E-Commerce App demo.