Skip to content

Developing Mobile Apps for Insights Hub

This article describes how to develop mobile apps for Insights Hub.

Mobile apps for Insights Hub can consist of multiple components which are categorized as follows:

Component Type Description
Native A native component runs on the mobile device and is not managed by Insights Hub.
Backend A backend component is an app which is hosted on a server and registered in Insights Hub to access Industrial IoT APIs. Native components can use its endpoints.

Prerequisites

  • Insights Hub user account on a developer tenant.
    If you don't have one, contact your tenant admin. For instructions, they may refer to Providing Access for New Users.
  • A Insights Hub developer role, either mdsp:core:Developer or mdsp:core:DeveloperAdmin.
  • If your app has a backend component: The backend component has been deployed to Cloud Foundry or some other server.

Registering a Mobile App in the Developer Cockpit

  1. Open the Developer Cockpit from the Launchpad and select the Dashboard tab.
  2. Click on Create new application.
  3. Select Type Mobile.
  4. Enter an arbitrary Display Name and a version number.
    • Insights Hub supports a Major.Minor.Patch scheme.
    • Versions must start with a major number >= 1.
    • The version cannot be changed after saving.
  5. Select the Infrastructure your mobile app is hosted in.
    • Apps with backend component: Select Cloud Foundry or Self Hosted (as deployed).
    • Apps without backend component: Select None.
  6. Enter an Internal Name which will be part of the URL for addressing backend components if available. The Internal Name cannot be changed after initial creation!
  7. Add the backend components if available.
  8. Configure an Android App Link and/or a universal link (optional).
  9. Click on Save.

Developer Cockpit - App Registration

Backend components can be accessed after registration using an endpoint of the following pattern:

https://gateway.{region}.{mindsphere_domain}/api/{internal_app_name}-{tenant_name}/{version}
https://gateway.eu1.mindsphere.io/api/app_1-my_tenant/v1

For more information on registering apps in the Developer Cockpit refer to Running a Cloud Foundry-Hosted Application or Integrating Self-Hosted Applications into Insights Hub or the Developer Cockpit manual.

Info

Adhere to the Restrictions mentioned in Gateway when making requests to either own registered applications or Industrial IoT APIs.

Android App Links and a universal links (iOS) are used to automatically redirect users back into the native mobile app after signing into Insights Hub. They are HTTP(S) based URLs and can be used for mapping to multiple apps. Along with the Android App Links and the universal links (iOS), custom-scheme based deep links are also supported. Both Android and iOS perform domain validation which requires the files specified below:

Android iOS
File Name assetlinks.json apple-app-site-association
Location https://{domain}/.well-known/ https://{domain}/.well-known
or https://{domain}
Behavior Asks the user to select the required app if the redirection fails. Flow is stopped if the redirection fails.

These files are hosted via HTTPS and served with content-type application/json.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.siemens.mdsp.maecfbackend",
    "sha256_cert_fingerprints":
    ["F9:98:C1:88:A8:35:F0:88:43:91:A8:C9:51:F6:E0:7B:13:F1:ED:C2:79:C2:6A:31:56:79:A0:DB:E7:89:B7:AA"]
  }
},
{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.companyname.mdsp.demo1",
    "sha256_cert_fingerprints":
    ["F4:C4:F5:07:74:C9:13:01:4A:86:72:24:A3:76:5D:E0:F4:28:D6:E6:C7:3D:25:18:94:0F:88:B2:52:6C:E1:46"]
  }
}]
{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "FM35W5TDQW.com.siemens.mdsp.MAECfBackend",
                "paths": [ "*" ]
            }
        ]
    }
}

For more information refer to Android and iOS developer guides.

Accessing Industrial IoT APIs

In contrast to browser based apps, session cookies are not available for mobile apps. Mobile apps can instead access Industrial IoT APIs as a web client using an access token.

Acquiring an Authorization Code

  1. Build the redirect URI of your mobile app:
https://{provider_tenant}-{internal_app_name}-{provider_tenant}.{region}.{ MindSphere_domain }/login
https://your_tenant-app_1-your_tenant.eu1.mindsphere.io/login

2.Build the URL below using the redirect URI. This URL takes users to the Insights Hub sign in screen. Refer to the documentation for the Developer Cockpit and Operator Cockpit for information on how to obtain the client ID.

https://{provider_tenant}.piam.{region}.{mindsphere-domain}/oauth/authorize?login_hint={user_tenant}&response_type=code&client_id={client_id}}&redirect_uri={redirect_URI}&state={random-value}`
https://your_tenant.piam.eu1.mindsphere.io/oauth/authorize?login_hint=user_tenant_1&response_type=code&client_id=mobile-client&redirect_uri=https://your_tenant-app_1-your_tenant.eu1.mindsphere.io/login
state parameter

The authorization protocol accepts a state parameter that allows to restore the induced state of the app. It is used to avoid the CSRF (Cross-site Request Forgery) attacks. Each state value is unique and associated with the initiated authentication request. You can prevent attacks by confirming that the state in the response matches the one from your request.

3.Call the prepared URL to get the authorization code.

The authorization code is included in the code field of the response.

Info

If an Android App Link or universal link is configured, the user is automatically redirected to the native mobile app after signing in. If the redirection fails, Android asks the user to select the app. On iOS the flow is stopped.

Getting an Access Token

The client ID and client secret are required for getting an access token. These are only displayed when an app is registered in the Developer or Operator Cockpit.

  1. Encode the combination of your client ID and client secret in Base64 format.

    • Combine client ID and client secret as shown below.

      {client_id}:{client_secret}
      
    • Encode the resulting string in Base64 format.

  2. Send an HTTP request to the OAuth Authorization Service:

  POST /oauth/token?grant_type=authorization_code&code={authorization_code}&redirect_uri=https://{provider_tenant}-{appname} -{provider_tenant}.{mindsphere-domain}/login
  Host: [https://%7bprovider_tenant%7d.piam.%7bregion%7d.%7bmindsphere-domain%7d]https://{provider_tenant}.piam.{region}.{mindsphere-domain}
  Content-Type: application/x-www-form-urlencoded
  tenant: {provider_tenant}
  Authorization: Basic {credentials-in-Base64-format}
{
  POST https://your_tenant.piam.eu1.mindsphere.io/oauth/token
  Content-Type: application/x-www-form-urlencoded
  Authorization: Basic YmFzZTY0IGVuY29kZWQgc3RyaW5n
  grant_type: authorization_code
  redirect_uri: https://my_domain/.well-known
  code: code_123
  tenant: my_tenant
}

The response contains an access token for accessing Industrial IoT APIs including backend components if available. This token is valid for 30 minutes.

{
  "access_token": {JSON_web_token}
  "token_type": "bearer",
  "refresh_token": {JSON_web_token}
  "expires_in": 1799,
  "scope": {list_of_scopes>}
  "jti": {unique_value}
}

Response Parameters

The scope parameter can be used to verify if required scopes are available. By default, all mobile apps have the scope {app_name}._access.
The response contains a refresh token for generating a new access token after it has expired. This token is valid for 12 hours.

Using refresh token in mobile application

Following refresh token template and example is used to generate the new access token:

POST /oauth/token?grant_type=refresh_token&refresh_token=[_REFRESH_TOKEN_] HTTP/1.1
Host: [_TENANT_].piam.eu1-int.mindsphere.io
Authorization: Basic [_BASE64_ENCODED_CLIENTID:SECRET_]
Content-Type: application/x-www-form-urlencoded
curl --location -g --request POST 'https://[_TENANT_].piam.eu1-int.mindsphere.io/oauth/token?grant_type=refresh_token&refresh_token=[_REFRESH_TOKEN_]' \
--header 'Authorization: Basic [_BASE64_ENCODED_CLIENTID:SECRET_]' \
--header 'Content-Type: application/x-www-form-urlencoded'

Accessing Industrial IoT APIs

  1. Request an access token as described above.
  2. Call your backend component if available or Industrial IoT APIs using this token.
    • Pass the access token as bearer token in the Authorization claim of the request header.
    • Industrial IoT APIs are accessed from the backend component, if available.
    • The backend component can reuse the authorization header to access Industrial IoT APIs.
POST https://gateway.{region}.{mindsphere_domain}/api/{endpoint} HTTP1/1
Content-Type: application/json
Authorization: Bearer {user_token}
POST https://gateway.eu1.mindsphere.io/api/assetmanagement/v3/assets HTTP1/1
Content-Type: application/json
Authorization: Bearer {user_token}
POST https://gateway.{region}.{mindsphere_domain}/api/{internal_app_name}-{tenant_name}/v1 HTTP1/1
Content-Type: application/json
Authorization: Bearer {user_token}
POST https://gateway.eu1.mindsphere.io/api/app_1-your_tenant/v1/ HTTP1/1
Content-Type: application/json
Authorization: Bearer {user_token}

Last update: December 11, 2023

Except where otherwise noted, content on this site is licensed under the Development License Agreement.