Preview 2.0 is now in Public Beta!
Read the Announcement

@nativescript/ionic-portals

Contents

Intro

A plugin that allows you to use Ionic Portals in NativeScript.

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

Installation

To install the plugin, run the following command from the root of your project:

npm install @nativescript/ionic-portals

Enable Ionic portals in your app

Below are the steps to enable Ionic Portal in your app.

1. Get a Portal API Key

Get a Portal API Key here.

2. Register portals

Register your Ionic Portals, by calling 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

3. Add portals view to markup

Core

  1. Register the plugin namespace with Page's xmlns attribute providing your prefix( ionic, for example).
<Page xmlns:ionic="@nativescript/ionic-portals">
  1. Access the IonicPortal view through the prefix and add it to markup.
<ionic:IonicPortal id="webPortal" />

Full code

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

Angular

  1. To add the IonicPortal view to the markup of any component, register it by adding the following code to the main.ts file:
import { registerElement } from '@nativescript/angular'
import { IonicPortal } from '@nativescript/ionic-portals'
registerElement('IonicPortal', () => IonicPortal)
  1. Add IonicPortal to markup.
<IonicPortal id="webPortal"></IonicPortal>;

Vue

  1. To add the IonicPortal view in the markup of any component, register it by adding the following code to the app.ts file:
import { IonicPortal } from '@nativescript/ionic-portals'

registerElement('IonicPortal', () => IonicPortal)
  1. Add IonicPortal to markup.
<GridLayout height="300" class="mt-3 p-3">
  <IonicPortal id="webPortal" />
</GridLayout>

Svelte

  1. To use the IonicPortal view in the markup of any component, register it by adding the following code to the app.ts file:
import { IonicPortal } from '@nativescript/ionic-portals'

import { registerNativeViewElement } from 'svelte-native/dom'
registerNativeViewElement('ionicPortal', () => IonicPortal)
  1. Add IonicPortal to markup.
<gridLayout height="300" class="mt-3 p-3">
  <ionicPortal id="webPortal" />
</gridLayout>

Send 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' })

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

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

ParameterTypeDescription
apiKeystringYour portal API key

setInitialContext()

IonicPortalManager.setInitialContext(id, initialContext)

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

ParameterTypeDescription
idstringThe portal id.
initialContextstringData provided as the initial context to the portal.

setAndroidPlugins()

IonicPortalManager.setAndroidPlugins(plugins)

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

ParameterTypeDescription
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)

ParameterTypeDescription
topic stringThe name of the topic/event
data anyOptional: 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.

ParameterTypeDescription
topic stringThe name of the topic/event to subscribe to.
callbackfunctionThe function invoked every time a message is sent via the topic with an optional data parameter.

unsubscribeFromTopic()

IonicPortalManager.unsubscribeFromTopic(topic, subscriptionId)
ParameterTypeDescription
topic stringThe name of the topic/event to unsubscribe from.
subscriptionIdnumberThe subscription id returned by subscribeToTopic().

configureLiveUpdates()

Note: configure before displaying the portal.

IonicPortalManager.configureLiveUpdates('webPortal', {
  appId: 'e2abc12',
  channel: 'production',
  syncOnAdd: true
})
ParameterTypeDescription
portalId stringThe portal id.
configIonicPortalLiveUpdateConfigLive update configuration.

syncNow()

IonicPortalManager.syncNow(['e2abc12'], false, status => {
  console.log('sync complete:', status)
})
ParameterTypeDescription
appIdsArray<string>Portal app ids to sync.
isParallelbooleanWhether to sync in parallel or not.
complete(status: string) => voidComplete callback.

getLastSync()

const lastSync = IonicPortalManager.getLastSync('e2abc12')
ParameterTypeDescription
appIdstringPortal 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

License

Apache License Version 2.0