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:

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 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.

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 MindSphere or the Developer Cockpit manual.

Android App Links and Universal Links¶

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 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:

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 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:

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 MindSphere 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

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

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

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 MindSphere 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}
}

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 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.

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}

Related Links¶

• Running a Cloud Foundry-Hosted Application
• Integrating Self-Hosted Applications into MindSphere

Any questions left?

Ask the community

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