Skip to main content

iOS Configuration

[中文版本]

Creating your iOS RainMaker Project

All the configuration related fields are kept in the property list file Configuration.plist. It can be found in the root directory of the project. Open it in Xcode and add value for properties described below.

AWS Configuration

RainMaker uses Amazon Cognito to provide authentication, authorization and user management in mobile apps. It also uses Amazon Web Services to provide RESTful APIs for communicating with devices. These settings need to be configured in the app and are clubbed into AWS Configuration key in Configuration.plist.

KeyTypeDescription
App Client IDString, RequiredUniquely identifies an app in a user pool. To get this value:
  • Login to ESP dashboard with superadmin credentials.
  • Go to Deployment settings, then from left navigation pane select "deployment details".
  • Find app client Id in Cognito details section. | | Authentication URL | String, Required | OAuth URL for third party login. Check Getting The Authentication URL | | Base URL | String, Required | Consistent part of each API endpoint. Follow Get Base Url steps to fetch the endpoint. | | Redirect URL | String | Add the following value here: <Bundle ID>://success. For steps to create Bundle ID see What are app bundle IDs in iOS. For steps to create Redirect URL see below. | | Claim URL | String, Optional | API endpoint for assisted claiming. This is not applicable for customer deployments so it can be removed or kept empty. |
note

How to get ESP dashboard URL?

  • ESP dashboard URL is in Cloudformation stack.
  • Also, super admin gets the email after RM deployment.
  • The mail gives the RM dashboard URL

App Configuration

KeyTypeDescription
Enable ScheduleBoolEnable(Yes) or Disable(No) scheduling functionality in the app.
Enable SceneBoolEnable(Yes) or Disable(No) scene feature in the app.
Enable Local ControlBoolEnable(Yes) or Disable(No) local control feature in the app.
Enable GroupingBoolEnable(Yes) or Disable(No) grouping feature in the app.
Enable SharingBoolEnable(Yes) or Disable(No) sharing feature in the app.

Consist of links that open your project related documentation within the app browser. Please provide valid URLs for each document type in the plist.

  1. Terms of Use
  2. Privacy Policy
  3. Documentation

Provision Settings

Configuration related to the provisioning feature of the app.

KeyTypeDescription
BLE Device PrefixStringApp will search for BLE devices with this prefix in the name.
ESP Allow Prefix SearchBoolApp will allow filtering by prefix search if this value is set to true. Filtering by prefix is not allowed otherwise.
ESP Security ModeStringPossible values
secure: for secure/encrypted communication between device and app.
unsecure: for unsecured/unencrypted communication between device and app.
ESP TransportStringPossible values
BLE: supports only BLE device provisioning.
SoftAP: supports only SoftAP device provisioning.
Both: supports both BLE and SoftAP device provisioning.
ESP Scan EnabledBoolEnables or disables scanning feature in the app.

App Group

App groups allow multiple apps produced by a single development team to maintain shared container (storage space). In this particular case this container is shared between the app and the notification service extension. It is used to store Node details which is required by Notification service to customise notification message. Find more information on app groups here.

Configuring App Group

  1. Go to apple developer console and into identifiers: https://developer.apple.com/account/resources/identifiers/list.
  2. Add a new identifier by clicking on + button.
  3. Select App Groups from the list and click on continue.

ios_config_app_group

  1. Add Description and Identifier for your app group and continue.

ios_config_register_app_group

  1. Review your changes and click on register to save it.

ios_config_register_app_group-1

Configure App Group in Xcode

  1. Open your Xcode project and go to Signing and Capabilties in main app target.
  2. Under App Groups capabilities select the app group that you have configured earlier.

ios_config_xcode_app_group

  1. Repeat steps 1 and 2 for PushNotificationExtension target in app.
  2. Open Configuration.plist file inside the project.
  3. Provide your app group id as the value of the key App Group.

ios_config_xcode_app_group-1

Push Notification Settings

Push notifications are enabled by default in the project. However, if you want to test notification at the time of development you need to change the endpoint from APNS to APNS_SANDBOX in the below method:

ios_config_endpoint_setting

Note: Remember to change the platform back to APNS when you distribute your app or upload it to App Store.

Add URL Scheme

App Bundle ID should be included in the Info.plist file of the RainMaker Project. Click on ESPRainMaker -> Info Tab. Scroll down to URL Types and expand. Add your URL scheme as shown below.

url_scheme

Creating Redirect URL

Redirect URL for ESP RainMaker app will be

com.espressif.rainmaker.softap://success

Replace com.espressif.rainmaker.softap with your application Bundle ID in the above data. So Redirect URL for your app will be

com.your_application_id.app://success

Additional Setting

You can also provide a theme colour to your application by setting the value of App Theme Color key in Configuration.plist. Provide it with a hex value of the intended colour, for e.g. #FFFFFF.

Alexa Account Linking

This account linking flow enables users to link their Alexa user account with their account in another service by starting from app. The following sections cover the app side configuration for alexa account linking.

Note: For more information on account linking and the cloud configuration please go here.

When you support universal links, iOS users can tap a link to your website and get seamlessly redirected to your installed app without going through Safari. If your app isn't installed, tapping a link to your website opens your website in Safari.

Please check iOS documentation for Universal Links.

You can go through the following steps in order to create a universal link for your app:

  1. In your app's Xcode project select the .xcodeproj file in the project navigator. In the Signing and Capabilites section, there is an Associated Domains section. Click on the + sign in the Domains section. Add the following information in that section: applinks:domain name of the associated website

2. Create the apple-app-site-association File

Create a file named apple-app-site-association. This file will contain the following JSON structure:

    {
"applinks": {
"apps": [],
"details": [
{
"appID": "ABCD1234.com.apple.wwdc",
"paths": ["*"]
}
]
}
}

note

Do not add .json to the apple-app-site-association file.


  1. The appID in the above file has the following format: TEAMID.Bundle ID of your app. Find more information on Team ID here and more information on app Bundle ID here.

  2. The paths array contains the list of paths for your website for which the app supports universal links. The * value for paths means that all possible paths for your website are supported.

  3. This apple-app-site-association file has to be placed in the root directory of your server or in the .well-known folder in the root directory of your server.

  4. The file needs to be accessible via HTTPS—without any redirects—at https://<domain>/apple-app-site-association or https://<domain>/.well-known/apple-app-site-association.

  5. You can validate your universal link using https://branch.io/resources/aasa-validator


Configuring Account Linking

In the Configuration.plist file, under the AWS Configuration section please ensure the following value is added:

KeyTypeDescription
Authentication URLStringOAuth URL. To get this value please refer here.

In the Configuration.plist file, under the ESP Alexa Configuration section the following values need to be added:

KeyTypeDescription
Alexa Client IdStringAlexa client ID. This can be found in:
- Go to Alexa dev console.
- Click on your skill
- Go to build tab
- Go to Permissions section
- Under permissions the alexa client ID can be found.
Alexa Client SecretStringAlexa client secret. This can be found in:
- Go to Alexa dev console.
- Click on your skill
- Go to build tab
- Go to Permissions section
- Under permissions the Alexa client secret can be found.
Alexa RM Client IdStringRefer section Steps to get Alexa and GVA client ID and copy the esp-rainmaker-alexa-skill client id
Skill IdStringSkill id of skill to be linked. This can be found in:
- Go to Alexa dev console.
- Click on your skill
- Go to Smart home section, where the skill ID can be found.
Skill StageStringPossible value:
live: for live skill
development: for a skill under development.
Redirect URLStringThis URL is provided in the calls to get alexa auth code and RainMaker (or custom user auth service) auth code. This is also used as the universal link for the iOS app. In order to find out how to configure universal link please check this link.
Alexa Access Token URLStringAPI endpoint used to fetch Alexa access token from Alexa auth code.
Check link for steps to get the value of the Alexa Access Token URL.

Apple Developer Settings

Creating App ID in Apple Developer Console

  1. Go to the Apple Developer portal: https://developer.apple.com/account/resources

  2. Click on Identifiers from the left menu. Click on the + button to register a new identifier.

    Apple Identifiers

  3. Select App IDs from the list and Continue.

    Apple Sign In

  4. Select App from the type.

    App type

  5. Add Bundle ID and Description for your app. Keep this Bundle ID the same as the one used in your RainMaker iOS app project.

    Register AppId

  6. Scroll down the page. Select Push Notifications and Sign in with Apple as capabilities. Click Continue.

    Register AppId

  7. Review and confirm the configurations.

  8. Take note of Team ID(App ID prefix) and Bundle ID value. Click on Register.

    Register AppId

On this page