This page will help you get started with Human API for iOS. You'll be up and running in no time! If you haven't already, please create a developer account as described on the [Start Here](🔗) page and come back here when you're done.
There are two main parts to integrating Human API with your application:
**A:** Allowing your users to authenticate their data
**B:** Accessing authenticated user data
This guide will walk through the implementation of the Human API iOS SDK to handle **part A** by allowing your users to authenticate their data within your application via the Human Connect popup . After the authentication process is complete, you will have the credentials needed to access user data from your server to complete **part B** as detailed in the [Data Retrieval](🔗) section of the documentation.
## Add the SDK to your Application
Copy the `
HumanAPI` folder from [the master branch of the iOS SDK](🔗) and place it in the base level of your project directory.
## Configure and Launch Human Connect
Now that you have the SDK, it's time to set up the authentication flow.
A user authenticates Human API by clicking the Connect Health Data button and authenticating their data directly with your application via Human Connect.
You can easily embed this authentication process directly into your iOS application.
First, add the button above (or another button of your choosing) as a `
UIButton` to the view you would like to launch Connect from and link it to an `
IBAction` in the view controller. You can then use this button to launch Human Connect in the following three steps:
# 1. Import the SDK ViewController and Protocol
In your ViewController.h file:
#import "HumanConnectViewController.h"` at the top
<HumanAPINotifications>` protocol to the ViewController e.g. `
@interface ViewController : UIViewController <HumanAPINotifications>`
# 2. Instantiate the HumanConnectViewController
Within the IBAction function you created, instantiate the `
You will need to pass these two values into the constructor:
|`||Unique ID of your developer portal application (found on the application settings page).|
|`||Custom endpoint on your server to handle the user token exchange. (You can add the default for now, we'll be implementing this in the second half of this guide.)|
# 3. Launch Connect for the User
startConnectFlowForNewUser: (NSString *)userId` to launch Connect for a new user and pass it the unique ID of the user in your system (This will be returned in the final step so that you can associate Human API credentials with the correct user.)
For now, this is all you need, but be aware that the next time the user launches Connect, you will need to use `
startConnectFlowFor: (NSString *)userId andPublicToken: (NSString *)publicToken`. You will get this token after the first successful authentication.
You will receive a `
publicToken` at the end of the user authentication process. This value must be passed into Human Connect every time the user opens the popup thereafter. It is not necessary for the first launch.
# Complete Launch Implementation
Altogether, your launch code for Human Connect should now look something like this:
If your authURL does not have SSL (https) such as the localhost example above, you will need to configure an App Transport Security Exception so that iOS does not block the POST request to an insecure URL. See the guide [here](🔗) for more information.
That is all that is needed to correctly launch Human Connect to allow your users to authenticate their data. The second half of the authentication process will occur on your server at the `
## [Server-Side] Handle Token Exchange
When a user authenticates a new data source in Human Connect, the Connect SDK will POST a `
sessionTokenObject` to your server for final processing via the `
authURL` specified on launch.
To complete the token exchange process, you should:
Add your `
clientSecret` to the `
sessionTokenObject` (clientSecret can be found on the app settings page in the developer portal)
POST the modified `
sessionTokenObject` from your server to Human API Tokens Endpoint:
Retrieve and store `
accessToken` and `
publicToken` on your server with the user model to be used to query user data from Human API. ([See here](🔗) for more information on what these values are.)
Return status `
200` or `
201` with payload containing `
publicToken` to store on device for future launches of Human Connect:
Here's an example of what this endpoint might look like in Node.js:
For more information on the server implementation, see [Finalizing User Authentication](🔗).
## Handle Callbacks from Human Connect
When the token exchange process is complete on your server, the Human API SDK will deliver your response to the `
(void) onConnectSuccess: (NSDictionary *)data` & `
(void) onConnectFailure:(NSString *)error` callbacks on the user's device.
Here, you should save the returned `
publicToken` on the device so that you can supply it to the HumanConnectViewController whenever the user launches Connect again in the future.
This is called when there is an error from Connect. Implementation of this callback is this therefore optional.
That's it! Now that you have the user's `
humanId` and `
accessToken`, you can start querying their data on your server for display in your app.
See the documentation in the [Data Retrieval](🔗) section of the documentation for more information.