Apple login practical guide
Apple login is a feature that lets users log in to the app with their own Apple account. Apple is an external authentication provider that authenticates users on the app's behalf. The user authenticates on the login screen that Apple draws, and the app gets a Hive Axyl login session from the result. A session is the state in which login is complete and the Hive Axyl SDK identifies the user.
To implement it, you must combine Apple Developer setup, Hive Console configuration, Hive Axyl SDK calls, recipe code calls, and app code. With the recipe code, the calls needed from getting credentials to activating the session are reduced to a single method.
Implementation scope
The work required to implement Apple login starts with getting credentials from Apple Developer and ends with showing the screen that matches the login result.
The work in each step falls into one of the following six categories.
| Category | Owner | Description |
|---|---|---|
| External console | App operator | Settings you configure in Apple Developer. |
| Hive Console | App operator | Settings you configure in the Hive Console. |
| Hive Axyl SDK | App developer | Hive Axyl SDK methods the app calls. |
| Add-on | App developer | Hive Axyl SDK extension packages that open the Apple login screen or the browser login page. |
| Recipe code | App developer | Recipe methods the app calls. |
| App code | App developer | Parts the app implements directly without going through Hive Axyl. |
Apple login has no Hive Axyl Server API calls. The app does not call the Add-ons directly; the recipe calls them instead. For this reason, Add-ons appear in the list of tasks the recipe performs internally rather than as a step category. For the meaning of parameters and the response fields, see the detailed procedures linked in each step.
Recipe
The Hive Axyl SDK provides login features as fine-grained methods. The Add-on call that gets credentials from Apple, the method that turns an authorization code into credentials in the browser-based method, the method that logs in with those credentials, the method that issues tokens, and the method that activates the session are all separate. Even to log in a single user, the app must combine the call order and the handling of intermediate failures itself.
A recipe is source code that completes that combination in advance. Instead of installing it as a package, you copy it into your project.
| Category | Location | Characteristics |
|---|---|---|
| Hive Axyl SDK | Unity packages com.com2usplatform.hiveaxyl.* | You install and use it. It provides authentication features as fine-grained methods. |
| Common recipe | Assets/Recipes/ProviderLogin/ | You copy and use it. It provides ProviderLoginRecipe, the result types, and the common code that uses credential sources. |
| Native recipe | Assets/Recipes/ProviderLogin.Apple/ | Provides AppleCredentialSource, used on iOS and macOS. |
| Browser recipe | Assets/Recipes/ProviderLogin.WebAuth/ | Provides AppleWebCredentialSource, used on Android and Windows, and the common browser login code. |
| Usage example | Assets/RecipeExamples/Authentication/ProviderLoginExample.cs | Code to read for reference. Its comments explain the login flow common to all external authentication providers and the parts the app must implement for each result. |
Recipes are code you copy and use
Recipes are copied into your app and become your app's code. You can use them as is or modify them to fit your app's policies.
The login recipe is not tied to a single external authentication provider. Only the part that gets Apple credentials is handled by ProviderLogin.Apple/ and ProviderLogin.WebAuth/; the rest of the process uses the same code as Google or Steam login.
OSs supported by the recipe
For Apple login, the way to get credentials differs by OS, so select the credential source that matches the OS the app is running on and pass it to the recipe. A credential source is an object that opens the Apple login screen or the browser login page and receives the user identifier and the authentication result.
| OS | Authentication method | Credential source | Implementation method |
|---|---|---|---|
| iOS, macOS | Native login screen drawn by Apple | AppleCredentialSource | Native method |
| Android, Windows | Apple login page opened in a browser | AppleWebCredentialSource | Browser-based method |
In the browser-based method, Apple sends the authentication result not to the app but to the HTTPS address registered in Apple Developer. Register the relay URL that Hive Axyl operates as this HTTPS address. The relay URL passes the received result to the app. If you call the source on an OS where the Add-on the method needs is not registered, it returns an Unavailable error. This does not mean the login was rejected; it means Apple login cannot run with that method in that environment.
What the app implements
The recipe handles only the steps from getting credentials to activating the session. The app implements the following items outside the recipe.
- The login screen and the screen transition after login
- Selecting the credential source for the OS
- Registering the app callback scheme that receives the result in the browser-based method on Android
- Creating and storing
DeviceKey - Storing the session tokens received from login
- Storing the email and name that Apple provides only on the first login in the native method
- The retry policy and user guidance messages for failures
Common prerequisites
Before you start implementing, prepare the following items.
| Item to prepare | Required | Category | Where to check |
|---|---|---|---|
| Create a project | Required | Hive Console | Create a project |
| Create an App ID | Required | Hive Console | Create an App ID |
| Register the Store App ID | Required | Hive Console | Register the store App ID |
| Check the Client ID | Required | Hive Console | Get the security key |
| Connect the SDK to your Unity project | Required | Hive Axyl SDK | Connect the SDK to your Unity project |
You enter the App ID when you initialize the SDK and the Client ID when you log in, so check both first. The Store App ID is the value Hive Axyl uses as the basis for integrating with the App Store, so you must register it before the Apple Developer setup. The SDK must be connected before you can install the authentication module and Add-ons in the following steps.
Next steps
If you have finished the prerequisites, start Implement Apple login.