Skip to content

Developing Mobile Apps for MindSphere

This article describes how to develop mobile apps for MindSphere.

Mobile apps for MindSphere 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 MindSphere.
Backend A backend component is an app which is hosted on a server and registered in MindSphere to access MindSphere APIs. Native components can use its endpoints.

Prerequisites

  • MindSphere 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 MindSphere 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.
    • MindSphere 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 MindSphere 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:

1
https://gateway.{region}.{mindsphere_domain}/api/{internal_app_name}-{tenant_name}/{version}
1
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 MindSphere or the Developer Cockpit manual.

Android App Links and a universal links (iOS) are used to automatically redirect users back into the native mobile app after signing into MindSphere. They are strictly HTTP(S) based URLs and can be used for mapping to multiple apps. 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 must be hosted via HTTPS and served with content-type application/json.

Click here to view example files for domain validation
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
[{
  "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"]
  }
}]
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "FM35W5TDQW.com.siemens.mdsp.MAECfBackend",
                "paths": [ "*" ]
            }
        ]
    }
}

For more information refer to Android and iOS developer guides.

Accessing MindSphere APIs

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

Acquiring an Authorization Code

  1. Build the redirect URI of your mobile app:

    1
    https://{provider_tenant}-{internal_app_name}-{provider_tenant}.{region}.{mindsphere_domain}/login
    
    1
    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 MindSphere sign in screen. Refer to the documentation for the Developer Cockpit and Operator Cockpit for information on how to obtain the client ID.

    1
    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}`
    
    1
    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.

MindSphere includes the authorization code 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.

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

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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
      POST https://{provider_tenant}.piam.{region}.{mindsphere-domain}/oauth/token
      Content-Type: application/x-www-form-urlencoded
      Authorization: Basic {credentials-in-Base64-format}
      grant_type: authorization_code
      redirect_uri: {app_link/universal_link}
      code: {authorization_code}
      tenant: {provider_tenant}
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    {
      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 MindSphere APIs including backend components if available. This token is valid for 30 minutes.

1
2
3
4
5
6
7
8
{
  "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.

Accessing MindSphere APIs

  1. Request an access token as described above.
  2. Call your backend component if available or MindSphere APIs using this token.

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

Any questions left?

Ask the community


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