Developing Mobile Apps for Insights Hub¶

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

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

Prerequisites¶

• Insights Hub user account on a developer tenant. If you do not have one, contact your tenant admin. For instructions, 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 must be deployed some other server.

Registering a Mobile App in Developer Cockpit¶

1. Open "Developer Cockpit" from the Launchpad and select the "Dashboard" tab.
2. Click "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 "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 "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/app1-mytenant1/v1

For more information on registering apps in the Developer Cockpit, refer to Integrating Self-Hosted Applications into Insights Hub or the Developer Cockpit document.

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

These files are hosted via HTTPs and served with content-type application/json. 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"]
      "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"]
      "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": ["*"]
      }
    ]
  }
  "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.

   TemplateExample

   https://{user_tenant}-{internal_app_name}-{provider_tenant}.{region}.{MindSphere_domain}/login
   

   https://mytenant1-app1-mytenant2.eu1.mindsphere.io/login
   

2. Build the URL below using the redirect URI.

   This URL takes users to the Insights Hub sign in screen. For information on how to obtain the client ID, refer to the documentation for the Developer Cockpit and Operator Cockpit.

   TemplateExample

   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://mytenant2.piam.eu1.mindsphere.io/oauth/authorize?login_hint=mytenant1&response_type=code&client_id=mobile-client&redirect_uri=https://mytenant1-app1-mytenant2.eu1.mindsphere.io/login
   

   state parameter

   The authorization protocol accepts a state parameter that allows restoring 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 can be found in the code field of the URL. Please use this code for authentication purposes.

   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.

   You may also face the below page after logging in. You can ignore this "error" page, and you will find the authorization code from the URL of the current page

   

   

   After obtaining the code, you can directly request the URL to be redirected to the home page of the mobile app.

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

   TemplateExample

   POST /oauth/token HTTP/1.1
   Host: {provider_tenant}.piam.{region}.{mindsphere-domain}
   Content-Type: application/x-www-form-urlencoded
   Authorization: Basic {credentials-in-Base64-format}
   
   grant_type=authorization_code
   code={authorization_code}
   redirect_uri=https://{user_tenant}-{appname}-{provider_tenant}.{mindsphere-domain}/login
   

   POST /oauth/token HTTP/1.1
   Host: {your_tenant}.piam.eu1.mindsphere.io
   Content-Type: application/x-www-form-urlencoded
   Authorization: Basic YmFzZTY0IGVuY29kZWQgc3RyaW5n
   
   grant_type=authorization_code
   code=code_123
   redirect_uri=https://my_domain/login
   

   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 HTTP/1.1

Host: {tenant}.piam.eu1.mindsphere.io
Authorization: Basic {base64_encoded_client_id:client_secret}
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
refresh_token={refresh_token}

curl --location --globoff --request POST 'https://mytenant1.piam.eu1.mindsphere.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic YmFzZTY0IGVuY29kZWQgc3RyaW5n' \
--data-urlencode 'grant_type=refresh_token&refresh_token=VuY29kZWQgc3RyaW5n1sdsdr2'
```url
curl --location --globoff --request POST 'https://mytenant1.piam.eu1.mindsphere.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic YmFzZTY0IGVuY29kZWQgc3RyaW5n' \
--data-urlencode 'grant_type=refresh_token&refresh_token=VuY29kZWQgc3RyaW5n1sdsdr2'

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 /api/{endpoint} HTTP/1.1
HOST: gateway.{region}.{mindsphere_domain}
Content-Type: application/json
Authorization: Bearer {user_token}

POST /api/assetmanagement/v3/assets HTTP/1.1
HOST: gateway.eu1.mindsphere.io
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbWRzcHN1cDIucGlhbS5ldTEubWluZHxxxxxx
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbWRzcHN1cDIucGlhbS5ldTEubWluZHxxxxxx

POST /api/{internal_app_name}-{tenant_name}/v1 HTTP/1.1
HOST: gateway.{region}.{mindsphere_domain}
Content-Type: application/json
Authorization: Bearer {user_token}

POST /api/app1-mytenant1/v1/ HTTP/1.1
HOST: gateway.eu1.mindsphere.io
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImprdSI6Imh0dHBzOi8vbWRzcHN1cDIucGlhbS5ldTEubWluZHxxxxxx

Related Links¶

• Integrating Self-Hosted Applications into Insights Hub

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