Skip to main content

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​

React Native​

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​

You can provide initial context when registering a Portal:

import { addPortal } from "@ionic/portals-react-native";

const portal = {
  name: "maps",
  startDir: "web",
  initialContext: {
    ic_example: "hello world",
  },
};

await addPortal(portal);

You can also override any initial context when rendering a Portal:

import { PortalView } from "@ionic/portals-react-native";

<PortalView
  portal={{
    name: "maps",
    initialContext: {
      ic_example: "goodbye",
    },
  }}
/>;

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.

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 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.

React Native​

Subscribe to messages from the web:

import { subscribe } from "@ionic/portals-react-native";

let emitterSubscription = subscribe("topic", (message) => {
  // Here you have access to:
  // message.data - Any data sent from the web
  // message.topic - The topic the message was published on
});

When you no longer need to receive events, unsubscribe:

emitterSubscription.remove();

You must unsubscribe to avoid any potential memory issues.

Publishing Messages​

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

From Web to React Native​

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

import { publish } from "@ionic/portals";
publish({ topic: "dismiss", data: "success" });

From React Native to Web​

To send messages from your React Native app to the web, use the publish method:

import { publish } from "@ionic/portals-react-native";
publish("weather", "sunny");

Examples​

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

Contents