Ionic Portals

@nativescript/ionic-portals #

Contents #

• @nativescript/ionic-portals
  • Contents
  • Intro
  • Installation
  • Enable Ionic portals in your app
    • 1. Get a Portal API Key
    • 2. Register portals
    • 3. Add portals view to markup
      • Core
      • Angular
      • Vue
      • Svelte
    • Send events from NativeScript to any web portal
      • Subscribe to events sent from web portals
      • Unsubscribe 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

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

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

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

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

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

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