@nativescript/ionic-portals

https://ionic.io/docs/portals

Ionic Portals are supercharged native WebView components for iOS and Android that let you add web-based experiences to native mobile apps.

Contents

• @nativescript/ionic-portals
  • Contents
  • Installation
  • Prerequisites
  • Usage
    • 1. Registering portals
    • 2. Use it in markup
      • Core
      • Angular
      • Vue
      • Svelte
      • Sending events from NativeScript to any web portal
      • Subscribing to events sent from web portals
      • Unsubscribing from events sent from web portals
  • IonicPortalManager API
    • register()
    • setInitialContext()
    • setAndroidPlugins()
    • publishTopic()
    • subscribeToTopic()
    • unsubscribeFromTopic()
    • configureLiveUpdates
    • syncNow
    • getLastSync
  • Using Capacitor Plugins with Ionic Portals
  • Notes
  • Additional Resources
  • License

Installation

npm install @nativescript/ionic-portals

Prerequisites

• Get a Portal API Key here.

Usage

1. Registering portals

To register your Ionic Portals, call the [IonicPortalManager] class's register method with the Portal API key.

import { Application } from '@nativescript/core';

import { IonicPortalManager } from '@nativescript/ionic-portals';

Application.on(Application.launchEvent, () => {
	// Register IonicPortals
	IonicPortalManager.register('<portal-api-key>');
});

// boot app here, for example:
Application.run({ moduleName: 'app-root' });

Create as many Portals as you need to use in your app.

The app will look for folders within its resources where the folder name is equal to the portal id you used to define each portal.

Given the following examples, ensure your web portal is built into the following folders:

• For iOS: App_Resources/iOS/webPortal
• For Android: App_Resources/Android/src/main/asssets/webPortal

2. Use it in markup

Core

<Page xmlns="http://schemas.nativescript.org/tns.xsd"
  xmlns:ionic="@nativescript/ionic-portals">
  <StackLayout class="p-20">
    <ionic:IonicPortal id="webPortal">
    </ionic:IonicPortal>
  </StackLayout>
</Page>

Angular

import { registerElement } from '@nativescript/angular';
import { IonicPortal } from '@nativescript/ionic-portals';
registerElement('IonicPortal', () => IonicPortal);

<IonicPortal id="webPortal"></IonicPortal>;

Vue

import { IonicPortal } from '@nativescript/ionic-portals';

registerElement("IonicPortal", ()=> IonicPortal)

 <gridLayout height="300" class="mt-3 p-3">
    <IonicPortal id="webPortal"/>
</gridLayout>

Svelte

import { IonicPortal } from '@nativescript/ionic-portals';

import {registerNativeViewElement} from "svelte-native/dom"
registerNativeViewElement("ionicPortal", ()=> IonicPortal)

<gridLayout height="300" class="mt-3 p-3">
    <ionicPortal id="webPortal"/>
</gridLayout>

Sending events from NativeScript to any web portal

To send events from NativeScript to any web portal, use the publishTopic() method:

IonicPortalManager.publishTopic('hello', { name: 'data from NativeScript' });

Subscribing to events sent from web portals

To subscribe to events sent from any web portal, call the subscribeToTopic method with the event name as the first argument and the event handler as the second argument.

const subscriptionId = IonicPortalManager.subscribeToTopic('useful-web-event', result => {
  console.log('received web portal useful-web-event with data:', result.data);
});

Unsubscribing from events sent from web portals

To unsubscribe from events sent from any web portal, call the unsubscribeFromTopic() method with the event name as the first argument and the subscription id as the second argument.

IonicPortalManager.unsubscribeFromTopic('useful-web-event', subscriptionId);

IonicPortalManager API

Allows you to interact with and configure portals via the following APIs.

register()

IonicPortalManager.register(apiKey)

Registers portals. Call it in the main.ts file, before the app boots, in the handler of the Application.launchEvent event.

| Parameter | Type | Description |:----------|:-----|:----------- | apiKey | string | Your portal API key

setInitialContext()

IonicPortalManager.setInitialContext(id,initialContext)

Used to set the initial context of any portal id before the portal is shown.

| Parameter | Type | Description |:----------|:-----|:----------- | id | string | The portal id. | initialContext | string | Data provided as the initial context to the portal.

setAndroidPlugins()

IonicPortalManager.setAndroidPlugins(plugins)

Defines the usage of non-official Capacitor Plugins via Android package names

| Parameter | Type | Description |:----------|:-----|:----------- | plugins | Array<string> | A list of non-official Capacitor package names.

publishTopic()

IonicPortalManager.publishTopic(topic, data)

Sends a message to any web portal by publishing a topic (aka. event)

| Parameter | Type | Description |:----------|:-----|:----------- | topic | string | The name of the topic/event | data | any | Optional: The payload to send with the topic.

subscribeToTopic()

subscriptionId: number = IonicPortalManager.subscribeToTopic(topic, (data?: any) => void))

Listens to any message sent from any web portal by subscribing to the specified topic. It returns a subscription id used to later unsubscribe from the topic.

| Parameter | Type | Description |:----------|:-----|:----------- | topic | string | The name of the topic/event to subscribe to. | callback | function | The function invoked every time a message is sent via the topic with an optional data parameter.

unsubscribeFromTopic()

IonicPortalManager.unsubscribeFromTopic(topic, subscriptionId)

| Parameter | Type | Description |:----------|:-----|:----------- | topic | string | The name of the topic/event to unsubscribe from. | subscriptionId | number | The subscription id returned by subscribeToTopic().

configureLiveUpdates

Note: configure before displaying the portal.

IonicPortalManager.configureLiveUpdates('webPortal', {
	appId: 'e2abc12',
	channel: 'production',
	syncOnAdd: true
})

| Parameter | Type | Description |:----------|:-----|:----------- | portalId | string | The portal id. | config | IonicPortalLiveUpdateConfig | Live update configuration.

syncNow

IonicPortalManager.syncNow(['e2abc12'], false, status => {
	console.log('sync complete:', status)
})

| Parameter | Type | Description |:----------|:-----|:----------- | appIds | Array<string> | Portal app ids to sync. | isParallel | boolean | Whether to sync in parallel or not. | complete | (status: string) => void | Complete callback.

getLastSync

const lastSync = IonicPortalManager.getLastSync('e2abc12')

| Parameter | Type | Description |:----------|:-----|:----------- | appId | string | Portal app id to check last sync.

Using Capacitor Plugins with Ionic Portals

Refer to this blog post.

Notes

For iOS: You may need to add IPHONEOS_DEPLOYMENT_TARGET = 12.0 to your App_Resources/iOS/build.xcconfig file. If your project contains App_Resources/iOS/Podfile, you may need to remove any post install handling which removes deployment targets, for example: Remove anything like this: config.build_settings.delete 'IPHONEOS_DEPLOYMENT_TARGET'

Additional Resources

• You can learn more about Ionic Portals at Opening Doors with Portals
  • Find the video's repo here

License

Apache License Version 2.0