EGYM Training Experience in the Partner Mobile Application

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

The EGYM training experience is delivered to partner apps as a Micro Web Application (MWA) that partners can integrate into their mobile apps. This approach provides partner app users with a cohesive experience while giving partners a framework for quick and seamless integration.

Context

The EGYM Micro Web Application should integrate seamlessly with the partner mobile application so that users perceive it as a native part of the partner app.

The purpose of this document is to provide high-level technical guidance on the steps a partner needs to take to integrate the EGYM MWA.

Integration between Mobile App and MWA

Suggested Steps

Step 1. Set up MWA infrastructure in the partner app (can be done autonomously by the partner):

• Review the documentation in the Ionic Portals section.
• Enable Ionic Portals and Live Updates in your mobile app.
• In addition to Live Updates, integrate ionic-cloud CLI into your native app build CI pipeline. This ensures the MWA is available on the device without relying on Live Updates and helps reduce live update counts. Use the following command (see the table below for parameter values):
  • Install Appflow CLI
  • appflow live-update download --token <token> --app-id <appId> --channel-name <channel> --zip-name <appId>-<channel>.zip

• Add the Capacitor plugins listed here.

Step 2. Integrate partner and EGYM products (requires collaboration with EGYM to understand current and future product use cases):

This step varies from partner to partner. Treat this section as a starting point for collaborative discussion rather than a prescriptive implementation guide.

• Set up communication between the mobile app and MWA:
  • Pass required parameters to MWA through initialContext.
  • Implement the Ionic Portals dismiss event to allow MWA to return from full screen to the native partner app, as described here.
• Provide a list of locations to map to EGYM locations.

Step 1. Set Up MWA Infrastructure in the Partner App

Ionic Portals and Related Documentation

1. Micro Web App Partner Documentation: https://developer.egym.com/mwa/docs/introduction
2. Ionic Portals Documentation: https://ionic.io/docs/portals/

Platform-Specific Setup

The sections below provide a quick-start overview for each platform. For complete details, refer to the official Ionic Portals documentation linked in each section.

// UIKit
func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    PortalsRegistrationManager.shared.register(key: "YOUR_PORTALS_KEY")
    return true
}

// SwiftUI
import IonicPortals

@main
struct PartnerApp: App {
    init() {
        PortalsRegistrationManager.shared.register(key: "YOUR_PORTALS_KEY")
    }
    var body: some Scene {
        WindowGroup { ContentView() }
    }
}

extension Portal {
    static let workouts = Portal(
        name: "workouts",
        startDir: "portals/workouts",
        liveUpdateConfig: .workoutsMwa
    )
}

extension LiveUpdate {
    static let workoutsMwa = Self(
        appId: "851e0894",
        channel: "${partnerName}production",
        syncOnAdd: true
    )
}

// SwiftUI
struct WorkoutsView: View {
    var body: some View {
        PortalView(portal: .workouts)
    }
}

// UIKit
class WorkoutsViewController: UIViewController {
    override func loadView() {
        self.view = PortalUIView(portal: .workouts)
    }
}

dependencies {
    implementation 'io.ionic:portals:0.12.0'
    implementation 'io.ionic:liveupdates:0.5.7'
}

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        PortalManager.register("YOUR_PORTALS_KEY")
    }
}

<application android:name=".MyApplication" ... >

PortalManager.newPortal("workouts")
    .setStartDir("851e0894-${partnerName}production")
    .setLiveUpdateConfig(
        applicationContext,
        LiveUpdate("851e0894", "${partnerName}production")
    )
    .create()

<io.ionic.portals.PortalView
    app:portalId="workouts"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

@Composable
fun WorkoutsPortal() {
    AndroidView(factory = { PortalView(it, "workouts") })
}

aaptOptions {
    // Override default to accommodate modern web app directory structures
    ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
}

// --- MWA download configuration ---
def appId = "851e0894"                  // MWA App Id (see configuration table)
def channel = "${partnerName}production" // Live Update channel
def ionicToken = ""                     // Appflow Personal Access Token

def zipName = "${appId}-${channel}.zip"
def zipFile = file("${project.projectDir}/${zipName}")
def destinationDir = file("src/main/assets/${appId}-${channel}")

tasks.register("cleanMwaAssets", Delete) {
    group = "appflow"
    description = "Clean previous Live Update assets and zip"
    delete destinationDir, zipFile
}

tasks.register("downloadMwaBuild", Exec) {
    group = "appflow"
    description = "Download Live Update zip from Appflow"
    dependsOn "cleanMwaAssets"
    workingDir project.projectDir

    doFirst {
        println "Downloading Live Update: appId=${appId}, channel=${channel}"
    }

    commandLine "bash", "-lc",
            "appflow live-update download " +
                    "--app-id=${appId} " +
                    "--channel-name=${channel} " +
                    "--token=${ionicToken} " +
                    "--zip-name=${zipName}"

    outputs.file(zipFile)
}

tasks.register("unzipMwaBuild", Copy) {
    group = "appflow"
    description = "Unzip Live Update into src/main/assets"
    dependsOn "downloadMwaBuild"

    from { zipTree(zipFile) }
    into destinationDir

    doFirst {
        destinationDir.mkdirs()
    }

    inputs.file(zipFile)
    outputs.dir(destinationDir)
}

tasks.register("cleanupMwaZip", Delete) {
    group = "appflow"
    description = "Remove downloaded zip after extraction"
    dependsOn "unzipMwaBuild"
    delete zipFile
}

// Hook into the build lifecycle so MWA is downloaded before each build
tasks.matching { it.name == "preBuild" }.all {
    dependsOn "cleanupMwaZip"
}

npm install @ionic/portals-react-native

import { register } from '@ionic/portals-react-native';

await register('YOUR_PORTALS_KEY');

import { PortalView } from '@ionic/portals-react-native';

const workoutsPortal = {
    name: 'workouts',
    startDir: 'portals/workouts',
    initialContext: {
        // Pass initial context properties here
    },
};

<PortalView
    portal={workoutsPortal}
    style={{ flex: 1 }}
/>;

const workoutsPortal = {
    name: 'workouts',
    startDir: 'portals/workouts',
    plugins: [
        {
            androidClassPath: 'com.capacitorjs.plugins.preferences.PreferencesPlugin',
            iosClassName: 'CAPPreferencesPlugin',
        },
        // Add other required plugins here
    ],
};

// AppDelegate.h
@interface RNAppDelegate : UIResponder <UIApplicationDelegate, RCTBridgeDelegate>

// main.m
return UIApplicationMain(argc, argv, nil, NSStringFromClass([RNAppDelegate class]));

dynamic_frameworks = ['Capacitor', 'CapacitorCordova']

pre_install do |installer|
    installer.pod_targets.each do |pod|
        if dynamic_frameworks.include?(pod.name)
            def pod.static_framework?; false; end
            def pod.build_type; Pod::BuildType.dynamic_framework; end
        end
    end
end

Versioning

The partner native mobile app and the Workouts MWA must use the same major versions of Ionic Portals, Capacitor Runtime, and Capacitor Core Plugins. Use the following versions:

• Ionic Portals: latest (v0.12.*)
• Capacitor Core: latest (v7.*)
• Capacitor Plugins: latest (v7.*)

Configuration Properties for Ionic Portals Initialization and MWA Updates

Capacitor Plugins

@capacitor-community/sqlite additional packages:

iOS:

SQLCipher

Android:

net.zetetic:android-database-sqlcipher
androidx.sqlite:sqlite
androidx.security:security-crypto

Step 2. Integrate Partner and EGYM Products

There are two options for integrating the partner native app with the EGYM MWA:

• 2.1 (Preferred): Link the partner app with EGYM ID using membershipId.
• 2.2: Link the partner app with EGYM ID using email.

2.1 Link Partner App with EGYM ID Using membershipId

Prerequisites:

• Integration with the partner's membership management system is required to link app profiles with EGYM ID (the user's account in the EGYM system). See https://developer.egym.com/mms-api-v2/apis/mms-v2.
• An EGYM ID (accountId) must be created using MMS API v2 before the member opens MWA.
• The membershipId must be unique within the partner's system.
• The member must complete EGYM ID registration by opening the EGYM MWA and accepting the EGYM ID terms of use.

An EGYM ID is required to access the EGYM MWA and EGYM machines. A critical part of the integration is linking user accounts from the partner mobile application (typically from the membership management system) with EGYM and persisting this link between application launches, so the user completes the linking flow only once.

The partner app shares user data with MWA to link an EGYM ID, including email, firstName, lastName, dateOfBirth, gymLocation, language, measurementSystem, gender, and a unique membershipId from the partner's system. See Properties that mobile app needs to pass to MWA Initial Context.

The membershipId maintains the link between the partner system and EGYM.

Securing the membershipId with JWT

To ensure a secure connection between EGYM and the partner system, the membershipId must be signed on the partner side and securely included in the initialContext:

1. Generate a key pair. The partner generates a public/private key pair and shares the public key with EGYM via a secure channel. EGYM stores the public key in a secret manager and uses it to decode and verify the membershipId.

   Example -- generate JWT keys:

   • Private Key Generation:
     • openssl genrsa -out ./private.key 4096
     • This generates a private.key file containing your private key.
       Do not share this file. Keep it secret. If someone obtains this private key, they can impersonate your system.
   • Public Key Generation:
     • openssl rsa -in private.key -pubout -outform PEM -out public.key
     • This creates a public.key file from your private key. Share this file with EGYM; it will be used to verify JWTs signed by your private key.

2. Create a signing endpoint. The partner implements (or extends an existing) backend endpoint that generates a short-lived JWT signed with the private key containing the membershipId.

   Expected JWT payload:

   • sub: the member ID in the partner's member management system
   • exp: token expiration timestamp

3. Pass the JWT at launch. When the user opens the EGYM entry point within the partner app:

   • The partner app requests a signed membershipId JWT from the partner backend.
   • The JWT is included in the initialContext under the membershipId field.
   • To optimize performance, the partner can cache tokens and reuse them until they expire, reducing backend calls.

4. EGYM verifies the JWT. The EGYM MWA reads the membershipId JWT from the initial context and forwards it to the EGYM backend. The EGYM backend accepts the JWT via its passwordless authentication API and verifies the signature, ensuring the request originates from an authorized and trusted source.

When the user opens the MWA, the following cases are possible:

2.1.1 User opens EGYM MWA for the first time

• User is notified about the creation of an EGYM ID.
• User accepts the terms of use and privacy policy.
• User accepts the health data processing consent.
• User can optionally accept sharing their data with the gym.

2.1.2 User has an existing EGYM ID

• User is prompted to enter their password.

2.1.3 User has previously logged in and the partner app already knows the EGYM ID

2.2 Link Partner App with EGYM ID Using Email

Note: The email must be unique within the partner's system and must not change.

An EGYM ID is required to access the EGYM MWA and EGYM machines. A critical part of the integration is linking user accounts from the partner mobile application with EGYM and persisting this link between application launches, so the user completes the linking flow only once.

The partner app shares user data with MWA to create an EGYM user, including email, firstName, lastName, dateOfBirth, gymLocation, language, measurementSystem, and gender.

2.2.1 User opens EGYM MWA for the first time

The most common scenario is when a partner app user does not yet have an EGYM ID. In this case, the MWA creates an EGYM ID and exerciser profile automatically and associates it with the partner account.

The partner application is responsible for passing a predefined set of attributes to the Workouts MWA through the Ionic InitialContext. See the Properties that mobile app needs to pass to MWA Initial Context section for the full list.

2.2.2 User has an existing EGYM ID

This scenario applies to users who already have an EGYM ID. The data structure passed through the Ionic InitialContext is the same as for Use Case 2.2.1. The MWA checks whether the user exists; if the email is found in the EGYM platform, the user is asked to enter their credentials. After authentication, the MWA triggers account linking and associates the EGYM ID with the partner account.

2.2.3 User has previously logged in and the partner app already knows the EGYM ID

This scenario applies when the user has already linked accounts and opens the app to track workouts. The MWA identifies this flow by the presence of both a refresh token and an access token in user preferences. To simplify the partner-side integration, the data structure passed through the Ionic InitialContext can be the same as for Use Case 2.2.1.

Properties That Mobile App Needs to Pass to MWA Initial Context

Gym Location Mappings

An important part of the integration between the partner and EGYM is configuring mappings between gym location identifiers in both systems. The EGYM backend uses gym location identifiers in user account linking flows (registration and login) as well as the workouts feature, so setting up location mappings is a prerequisite for the web app to function properly.