Skip to main content

Update Portals with Live Updates

Ionic Appflow's Live Update feature allows web teams to deploy updated web assets independently on their own release cycle. Live Updates can be used in conjunction with Portals to ensure the latest version of web assets are available in Portals projects.

Tooling provided by Ionic allows native teams to synchronize Portals with Live Updates at build-time and run-time, utilizing fully compliant over-the-air updating for a seamless content delivery experience.

In this tutorial, you will learn how to leverage Live Updates to synchronize the latest web assets within a Portals project. You will also learn how to use the Live Updates SDK to deliver updated web assets to end users over-the-air.

This tutorial is specifically designed for iOS and Android developers.

Overview​

In this tutorial, you will extend the Jobsync superapp built as part of the Portals training. Jobsync is an intranet-themed superapp that provides typical employee functions such as expense management. Web teams build employee functions as web apps that Jobsync presents through Portals.

Currently, web assets are synchronized with Jobsync by copying local resources into native iOS/Android projects at build-time. This scenario is not ideal for two reasons:

  1. Native developers must be able to access local paths to the web assets at build-time.
  2. Web teams cannot update their web assets without the new release of the native app.

A new function, a contact directory, is to be added to Jobsync. The contact directory has been registered with Appflow; by using Appflow's Live Update feature both concerns can be addressed.

Appflow Terminology​

Appflow is primarily focused towards web teams; however, it is beneficial to understand certain Appflow terms before using Live Updates with Portals:

  • App: Web applications registered within Appflow, each with a unique identifier (App ID).
  • Channel: A channel serves as a deployment lane for an Appflow app. Native apps and the Portals CLI can subscribe to these channels to receive updates.
  • Build: Individual web asset builds for an Appflow app are stored and can be assigned to that app's channels.
  • Live Update: The specific build referenced by a channel, capable of delivery to native apps and the Portals CLI.
note

A deeper-dive of Appflow for native developers can be found in the Getting Started guide.

Disclaimer

In this tutorial, two Live Update channels are used for both the Portals CLI and Live Updates SDK configuration: initial and production. This is to ensure that a Live Update is available to download over-the-air.

In a real world scenario, the same Live Update channel would be used in both the Portals CLI and Live Updates SDK configuration for any given deployment lane.

Setting up the project​

This tutorial utilizes the same repository used for the Portals training.

Make sure that you have followed the instructions in the "What you will need" section of the training introduction before proceeding.

The repository contains branches for different trainings and tutorials, the start-using-liveupdates branch corresponds to this tutorial:

terminal

_10
cd ./tutorials-and-trainings-portals
_10
git checkout start-using-liveupdates

Open either the Xcode project (/ios/Jobsync.xcodeproj) or the Android studio project (/android) depending on which platform you are developing for.

Before building or running the project, you will need to register your Portals key:

Jobsync.swift

_16
import SwiftUI
_16
import IonicPortals
_16
_16
@main
_16
PortalsRegistrationManager.shared.register(key: "YOUR_KEY_HERE")

Seed a Portal at build-time​

The Jobsync project uses the Portals CLI's sync command to bundle the web assets that will be presented through Portals. Currently, all web assets to be bundled are synchronized from relative paths within the repository:

ios/.portals.yaml

_10
sync:
_10
- file-path: ../web/apps/expenses/dist
_10
directory-name: portals/expenses
_10
- file-path: ../web/apps/tasks/dist
_10
directory-name: portals/tasks
_10
- file-path: ../web/apps/time-tracking/dist
_10
directory-name: portals/time-tracking

The sync command can be configured to pull down the latest Live Update available to any given Appflow app; also referred to as "seeding a Portal". Doing so is good practice as it ensures the native release ships with the latest web assets.

Update .portals.yaml to include an entry for the contact directory function which has been registered with Appflow:

ios/.portals.yaml
sync:
  - file-path: ../../web/apps/expenses/dist
    directory-name: src/main/assets/portals/expenses
  - file-path: ../../web/apps/tasks/dist
    directory-name: src/main/assets/portals/tasks
  - file-path: ../../web/apps/time-tracking/dist
    directory-name: src/main/assets/portals/time_tracking
  - app-id: b5e647f7
    channel: initial
    directory-name: src/main/assets/portals/contacts
token: ion_JKrBJgyBVJlA4o3FknCviCtzS6to2hGX2pjQ2T6nbt

Now at build-time, Jobsync will pull down and bundle the latest version of the contact directory feature (provisioned in Appflow with the App ID b5e647f7) available on the initial channel within the designated directory.

note

An Appflow Personal Access Token is required for the Portals CLI to authorize with Appflow.

The Jobsync app displays a list of available employee functions by iterating through a static array. Before the contact directory can be accessed at run-time, an entry for it must be added.

Add an entry to the list for the contact directory function:

Portals/WebApps.swift

_21
import Foundation
_21
import IonicLiveUpdates
_21
_21
struct WebAppMetadata: Hashable {
_21
var name: String
_21
WebAppMetadata(name: "contacts", description: "Quickly locate and update contact records.")

Build and run the Jobsync app and navigate to the dashboard view. Select the "Contacts" feature from the list, and the seeded Live Update will load within the Portal.

Update a Portal over-the-air​

When working with multiple feature teams, coordinating a single release cycle is difficult. Luckily, Live Updates can be used to deliver web asset updates over-the-air, allowing web teams to update their Portals independent of other teams. The Live Updates SDK is used to programmatically tie a Portal with a corresponding Appflow app and channel. At run-time, the Live Updates SDK will download and apply the latest Live Update if available.

The Live Updates SDK comes bundled with the iOS IonicPortals dependency, but must be explicitly added on Android. If needed, add the Live Updates SDK to the app level build.gradle.kts file:

build.gradle.kts

_10
implementation("io.ionic:liveupdates:[0.0,1.0)")

Live Updates must be configured as part of the Portal creation process, by passing in a LiveUpdate object into the liveUpdateConfig property.

Since Jobsync dynamically creates Portals based on a static array of WebAppMetadata, the first step is to adjust the data type to include an optional property where Live Update configuration data can be set:

Portals/WebApps.swift

_25
import Foundation
_25
import IonicLiveUpdates
_25
_25
struct WebAppMetadata: Hashable {
_25
var name: String
_25
var description: String
_25
var liveUpdate: LiveUpdate?
_25
_25
var displayName: String {
_25
self.name.replacingOccurrences(of: "-", with: " ").capitalized
_25
}
_25
}
_25
_25
struct WebApps {
_25
static let metadata: [WebAppMetadata] = [
_25
WebAppMetadata(name: "expenses", description: "Submit expenses for business purchases."),
_25
WebAppMetadata(name: "tasks", description: "Track tasks for transparent project updates."),
_25
WebAppMetadata(name: "time-tracking", description: "Stay on schedule by tracking time spent."),
_25
WebAppMetadata(
_25
name: "contacts",
_25
description: "Quickly locate and update contact records.",
_25
liveUpdate: LiveUpdate(appId: "b5e647f7", channel: "production")
_25
)
_25
]
_25
}

Then, the view that displays Portals within the app needs to be updated to conditionally add Live Update configuration, if available:

Portals/WebAppView.swift

_42
import SwiftUI
_42
import IonicPortals
_42
_42
struct WebAppView: View {
_42
@EnvironmentObject var credentialsManager: CredentialsManager
_42
@Environment(\.dismiss) var dismiss
_42
let metadata: WebAppMetadata
_42
_42
var body: some View {
_42
PortalView(
_42
portal: createPortal()
_42
)
_42
.ignoresSafeArea()
_42
.navigationBarBackButtonHidden()
_42
.task {
_42
let stream = PortalsPubSub.subscribe(to: "navigate:back")
_42
for await _ in stream {
_42
self.dismiss()
_42
}
_42
}
_42
}
_42
_42
private func createPortal() -> Portal {
_42
var portal = Portal(
_42
name: metadata.name,
_42
startDir: "portals/\(metadata.name)",
_42
initialContext: credentialsManager.credentials!.toJSObject()
_42
)
_42
.adding(AnalyticsPlugin())
_42

Re-build and run the Jobsync app and navigate to the dashboard view. Select the "Contacts" feature from the list, then press the back button. Re-selecting the "Contacts" feature will load a new version of the contact directory function, containing a search bar that filters the contacts from the list.

Thanks to the Live Updates configuration added for this Portal, the latest version of the contact directory was downloaded and applied the next time the Portal was loaded.

Behind-the-scenes, the Live Updates SDK performs the following actions by default:

  1. The first time a Portal is created, it will check to see if an update is available.
  2. If so, the update is downloaded to the device and setup with the Portal.
  3. The next time the Portal is loaded, the update will be applied.

Developers can also manually apply Live Updates, see "Syncing with Live Updates" (iOS or Android) for more information.

Conclusion​

In this tutorial, you combined Live Updates with Portals to ensure the Jobsync application delivers the latest contact directory experience. Using Live Updates with the Portals CLI ensures the latest web assets are bundled with native applications at build-time, and using the Live Updates SDK provides the ability to update web assets presented through Portals over-the-air. Live Updates allow web teams contributing to your Portals projects to deploy updated experiences without directly impacting native development.

Contents