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

EGYM training experience is provided for partner apps in the form of Micro Web Application(MWA) that partner can integrate in their mobile apps. The idea is to provide users of the partner app with cohesive user experience and provide partners with the framework for quick and seamless integration.

Context

EGYM Micro Web Application should seamlessly integrate with the PARTNER mobile application, so application users see it as an integral part of the PARTNER application.

The purpose of this document is to provide a high-level technical guidance on steps PARTNER needs to take to to introduce EGYM MWA integration.

Integration between Mobile App and MWA

Suggested steps:

Step 1. Bring MWA infrastructure to Partner app(could be done autonomously by the partner): :

• Review the documentation from Ionic Portals section
• Enable Ionic Portals and Live updates in your mobile app
• Separately, in addition to Live updates, to ensure MWA app is available on the device without relying on Live Update and to save on live updates count, integrate ionic-cloud cli into native app build CI pipeline, use the following command, find parameters in table below
  • install appflow cli
  • appflow live-update download --token <token> --app-id <appId> --channel-name <channel> --zip-name <appId>-<channel>.zip

• Add 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 would likely vary from Partner to Partner, so treat this part of the documentation as something that we would need to work together and this not necessarily should be implemented as is.

• Introduce the communication between mobile app and MWA
  • pass required parameters to MWA through initialContext
  • Implement Ionic Portals dismiss event to allow MWA to exit back from full screen to the native PARTNER app as described here
• Provide list of locations to map them to EGYM locations

Step 1. Bring MWA infrastructure to 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/

Documentation

- iOS

https://ionic.io/docs/portals/for-ios/getting-started https://ionic.io/docs/portals/for-ios/live-updates

- Android

https://ionic.io/docs/portals/for-android/getting-started https://ionic.io/docs/portals/for-android/live-updates

- React Native

https://ionic.io/docs/portals/for-react-native/getting-started

Versioning

It is important that PARTNER native Mobile App and Workouts MWA use the same major versions of Ionic Portals, Capacitor Runtime and Capacitor Core Plugins. It is proposed to use the following versions:

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

Configuration properties that should be used to initialize Ionic Portals framework and pull 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 2 options how to integrate partner native app and EGYM MWA:

2.1. Preferred. Link partner app with EGYM ID using membershipId.

2.2 Link partner app with EGYM ID using email.

2.1 Link partner app with EGYM ID using membershipId.

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

In order to access EGYM MWA and EGYM machines EGYM ID is required. So an important part of the integration is the process of linking user accounts from the PARTNER mobile application(usually it comes from the membership management system) with EGYM and preserving this information between application launches, so the user goes through the linking flow only once.

PARTNER app shares with MWA user data to link an EGYM ID such as(email, firstName, lastName, dateOfBirth, gymLocation, language, measurementSystem, gender and unique membershipId from the PARTNER system). See section "Properties that mobile app needs to pass to MWA Initial Context"

The presence of membershipId is needed to maintain a link between membershipId in PARTNER system and membershipId in EGYM.

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:

• 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 for decoding and verifying membershipId.

  • Example: Generate JWT keys
    • Private Key Generation:
      • openssl genrsa -out ./private.key 4096
      • This will generate a private.key file in your current directory containing your private key.
        ⚠️ Do not share this file and 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. You can share this file with EGYM, and it will be used to verify JWTs signed by your private key.

• PARTNER implements (or extends an existing) backend endpoint that generates a short-lived JWT signed with the private key and containing the membershipId.

  • Expected JWT payload:
    • sub: the member ID in the PARTNER’s member management system
    • exp: token expiration timestamp

• 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, PARTNER can implement caching to reuse tokens until they expire, reducing backend calls.

• EGYM MWA reads the membershipId JWT from the initial context and forwards it to the EGYM backend.

• The EGYM backend accepts the JWT in its passwordless authentication API and verifies the signature.
  This ensures that the request originates from an authorized and trusted source.

When user opens the MWA these are the possible cases

2.1.1 User opens up EGYM MWA first time

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

2.1.2 User has created EGYM ID before

• User should be prompted to enter the password

2.1.3 User logged in before and partner app already knows EGYM ID

2.2 Link partner app with EGYM ID using email

*email should be unique within partner's system and should not change

In order to access EGYM MWA and EGYM machines EGYM ID is required. So an important part of the integration is the process of linking user accounts from the PARTNER mobile application with EGYM and preserving this information between application launches, so the user goes through the linking flow only once.

• PARTNER app shares with MWA user data to create an EGYM user such as(email, firstName, lastName, dateOfBirth, gymLocation, language, measurementSystem, gender).

2.2.1 User opens up EGYM MWA first time

The most common scenario of account linking flow is when an PARTNER app user doesn't have an EGYM ID(EGYM account). In this case, MWA will create an EGYM ID(EGYM account) and exerciser profile under the hood and associate it with PARTNER account.

PARTNER application will be responsible for passing a predefined set of attributes of Workouts Micro Web App (MWA) through the Ionic InitialContext. The list of these attributes can be found in the “Properties that mobile app needs to pass to mwa section section

2.2.2 User has created EGYM ID before

This integration scenario is applicable for the users who already have an EGYM ID(EGYM account). The structure of the data passed by PARTNER through the Ionic InitialContext is the same and for the Use Case 2.2.1. The MWA will check the existence of the user and if such email exists in EGYM platform will ask a user to enter his credentials. After that, it will trigger account linking and associate EGYM ID(EGYM account) with PARTNER account.

2.2.3 User logged in before and partner app already knows EGYM ID

This scenario is applicable for cases when the user has already linked the accounts and opens the app to track workouts. The MWA will distinguish this flow by the presence of the refresh token as well as the access token in user preferences. In order to simplify the integration from the PARTNER side the structure of the data passed to the web app through 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 PARTNER and EGYM is to configure mappings between gym location identifiers in both systems. EGYM backend uses gym location identifiers in user account linking flows (user registration and login) as well as workouts feature, so the setup of location mappings is a prerequisite for a web app to function properly.