Deploying Metric Insights' Custom Mobile Apps at Your Organization

This document will describe the steps needed to deploy the Metric Insights mobile app on iOS; Android is much more simple — a small section at the bottom is dedicated to it.

PREREQUISITES

  • Submit your information via the Custom Mobile Build form (please request it from [email protected])
  • Receive the Xcode project and APK for your custom mobile build from Metric Insights team
  • Acquire an Apple Developer Enterprise account

Mobile App Deployment Architecture

MI-MobileAppArchitecture.pdf

1. Create a New Metric Insights App ID

Access iOS Dev Center > Developer Account page

  1. Under Program Resources, select Certificates, IDs & Profiles
  2. In the following page, select Identifiers
  3. Click the plus button next to Identifiers

2. Register an App ID

  1. Define the Name of a new App ID
  2. Select Explicit and define Bundle ID
  3. Under Capabilities, select Push Notifications to enable them for the application
  4. [Continue]

3. Register a New Identifier

4. [Optionally] Specify Deployment Details

You will see the info about App ID that you have created.

Optionally, you can provide deployment details – whether the application is for distribution or development purposes.

For development: select the corresponding option and click [Continue].

For distribution:

  • Estimated Distribution Volume, App Security Mechanisms, App Audience: Specify based on the organization's needs;
  • Distribution Method: "MDM Deployment" is recommended.

Confirm that the information is accurate below. Click [Continue].

5. Complete Registration

Review registration details and [Register]

6. Create the Push Notification Certificate

  1. Access the newly-created application
  2. Access Push Notifications > Configure
  3. Generate a certificate
    • The certificate can be of two types: Production ([app_id].pem) or Development ([app_id].dev.pem)
    • To generate a certificate, you will need a certificate signing request. If you don't have it, follow these instructions to create one.

7. Upload the Certificate to MI

  1. Once created, download the certificate
  2. Upload it to the 'certificates' directory on your Metric Insights instance at:
/opt/mi/iv/data/certificates

There is a System Variable in Metric Insights that determines which type of certificate should be used (see the step below).

Define the Type of Certificate to Be Used in Metric Insights

Access Admin > System > System Variables

  1. For MOBILE_PUSH_ENVIRONMENT, define the certificate type to be used and [Save]
  2. [Commit changes]

Once the certificates have been created and are in the appropriate locations, Push Notifications should begin to work.

NOTE: The certificates should be added to all supported instances (dev, prod, etc.).

If Needed, Copy the Passphrase You Created into Metric Insights

Access Admin > System > System Variables

  1. For MOBILE_PUSH_PRIVATE_KEY_PASSPHRASE, paste the passphrase [Save]
  2. [Commit changes]
  3. Log out from the application on the mobile device and log back in
  4. Go to My Settings in Metric Insights and resend the test alert (see the step below)

NOTE: You'll need to go through these steps for every server.

Test Alerts for an Individual User

  1. From your user menu, access My Mobile
  2. [Send Test Alert]. Assuming the device is logged in to the instance from which you are sending the test, you should receive it on your phone.

To test Alerts more thoroughly, you can create an Alert and then re-trigger it by following these steps.

Android Requirements

On Android, there is no additional setup required for receiving Push Notifications. There is a key pair that comes with the MI instance and the Android app, and as there is no third party gatekeeper that manages notifications (e.g. Apple Push Notification Service), it should work as-is.