Ionic Portals

@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" />
  </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.

setInitialContext() #

IonicPortalManager.setInitialContext(id, initialContext)

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

setAndroidPlugins() #

IonicPortalManager.setAndroidPlugins(plugins)

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

publishTopic() #

IonicPortalManager.publishTopic(topic, data)

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

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.

unsubscribeFromTopic() #

IonicPortalManager.unsubscribeFromTopic(topic, subscriptionId)

configureLiveUpdates #

Note: configure before displaying the portal.

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

syncNow #

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

getLastSync #

const lastSync = IonicPortalManager.getLastSync('e2abc12')

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