The only user permission required by the SetSDK is Notifications. The SDK requires this permission in order to receive new Notification recipes from your Dashboard and to trigger new API responses for your app.
Notification Permissions Setup
Enable Push Notifications
The first step is to enable Push Notifications in your application. Open your project in Xcode. Next, go to App Settings => Capabilities. Flip the switch for Push Notifications to On.
Enable Remote Notifications in Background Mode
Next, enable Remote notifications in the Background Modes. Go to App Settings => Capabilities. Scroll down to Background Modes and check the box beside Remote notifications.
Prompting User for Permission
In order for your app and Set to receive and display notifications, you need to prompt the user for permission to do that. It’s up to you to decide exactly when to ask the user for permission, but it should be shortly after your app launches. You can use Set’s helper function to easily do that, or use UNUserNotificationCenter’s function.
Add APN Keys to Your Dashboard
Next, you'll need to add your APN keys from Apple to your Dashboard. Set uses the APN to send Notifications you request and to send new Recipes to your mobile devices and process these requests in the background.
Creating APN Keys
- Visit the Apple Developer Account.
- Click on Certificates, Identifiers & Profiles.
- Go to Keys in the lefthand menu.
- Click the "+" button in the upper right-hand corner.
- Create a descriptive name for you new Key.
- Check the box under Enable to the left of APNs.
- Hit Continue.
- In this page, copy the value next to Key ID, this is the APN Service Key ID you'll need to drop into your Dashboard.
- Click Download.
- Finally, you'll copy the contents of the file you downloaded. The contents of that file are what go into APN Service Key.
Getting your Team ID
- Visit the Apple Developer Account.
- In the menu at the top, click Account.
- In the menu on the left, click Membership.
- Scroll down and copy the value in the row, Team ID
Add Your Keys to Set
We require the following information:
- Team ID
- APN Service Key ID
- APN Service Key
You can cut and paste your keys into Set by logging into your Dashboard, going to Settings and scrolling down to APN Credentials.
Location Permissions Setup (Optional)
Location and motion activities aren’t required for Set to run, but if they’re available, the speed, amount, and quality of Set’s learning will increase. SetSDK will NOT automatically attempt to enable these features, and will NOT prompt your users for location and motion activity data permissions. It’s up to you to provide the UX of when and where in your app to ask the user, if at all, for these permissions. SetSDK provides some helper functions to make it easy to trigger the prompts for those permissions.
[success] Safe, quiet, and efficient!
Set has little to no observable impact on your apps battery consumption. Set never causes a the blue bar location tracking as experienced by some iOS 11 location apps.
See documentation on the helper functions for more information.
If you decide to enable Location permissions, we recommend reviewing Apple’s guidelines on the right way to do it. Keep in mind two strong recommendations from Apple.
- Provide rich explanation of why you need access to location and how it makes your app run better. We provide a few examples below that might pertain to your app when using Set.
- Escalate a user’s permissions stepwise, first asking for access to Foreground Location and later asking for access to Background Location.
Enable Foreground Location
Set improves when it has access to Background Location, but it is still useful and in your best interest to first request Foreground Location permission from your users.
Enable Location in Background
First, enable Remote notifications in the Background Modes. Go to App Settings => Capabilities. Scroll down to Background Modes and check the box beside Location updates.
Add Usage Description to Info
Before requesting Foreground or Background Location data, you must provide your user with a description of why you need that data. We strongly recommend you explain to the user a feature or features they cannot use without accessing this data, and then, only request access to their location data when they request those features.
Set can help you add a variety of new features to your app with access to Background Location. If you plan to enable Location in order to use Set, consider explaining the features they'll gain from sharing the data. Here are some Examples,
- We can send you fewer notifications by limiting them to places and times you actually use our app.
- We can enable new preferences linked to your behaviors, such as being at home, or commuting to work.
Now, once you have your description, add it as a new row in your Info. Go to App Settings => Info. Select an existing row and click the "+" button. Add a new entry with key, "Privacy – Location Always Usage Description." and enter your description for the value.
Prompt the User for Permission
Again, we recommend only requesting the permission as soon as the user wants a feature that requires background location. As soon as they do, you can run our helper function SetSDK.requestLocationAlways() to present them the proper dialog.
Motion Permissions Setup (Optional)
Set uses Motion data to help label user behaviors and detect context changes. Without Motion permissions, Set’s Context APIs will not be available for some behavior types.
Add Usage Description to Info
Just like Location data, you must create a description to present to your users for why you want access to their motion data. Once you have one, Go to App Settings => Info. Select an existing row and click the "+" button. Add a new entry with key, "Privacy - Motion Usage Description." and enter your description for the value.
Prompt User for Permission
Prompting the user for Motion permissions can be tricky, so we have created a small helper for issuing the prompt.
Trigger this function as soon as you feel your user will understand your description for needing access to motion data.
If you don’t use the above function and have previously/independently started Core Motion related services, you must still explicitly enable motion data tracking within SetSDK by calling the method above.
[success] Let's do this!
All the house-keeping is behind you! Check out the Starting Set section for next steps.
Get in touch
- If you need help, shoot us a message at firstname.lastname@example.org or ping us on our Slack community.
- If found a bug, or have a feature request, add an Issue on the SetSDK Repo.
- Follow us on Twitter for product updates: @everyset