为 iOS 提供使用 Apple 登录功能的库。
expo-apple-authentication
为 iOS 提供 Apple 身份验证。它尚不支持 Android 或 Web。
¥expo-apple-authentication
provides Apple authentication for iOS. It does not yet support Android or web.
任何包含第三方身份验证选项的应用都必须提供 Apple 身份验证作为符合 App Store 审核指南的选项。有关更多信息,请参阅 使用 Apple 登录 网站上的 Apple 身份验证。
¥Any app that includes third-party authentication options must provide Apple authentication as an option to comply with App Store Review guidelines. For more information, see Apple authentication on the Sign In with Apple website.
¥Installation
-
npx expo install expo-apple-authentication
If you are installing this in an existing React Native app (bare workflow), start by installing expo
in your project. Then, follow the additional instructions as mentioned by library's README under "Installation in bare React Native projects" section.
¥Configuration in app config
如果你在项目中使用配置插件(EAS 构建 或 npx expo run:[android|ios]
),则可以使用其内置的 配置插件 配置 expo-apple-authentication
。该插件允许你配置无法在运行时设置的各种属性,并且需要构建新的应用二进制文件才能生效。如果你的应用不使用 EAS Build,则你需要手动配置包。
¥You can configure expo-apple-authentication
using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]
).
The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use EAS Build, then you'll need to manually configure the package.
¥Setup iOS project
要在应用中启用“使用 Apple 登录”功能,请在项目的应用配置中将 ios.usesAppleSignIn
属性设置为 true
:
¥To enable the Sign In with Apple capability in your app, set the ios.usesAppleSignIn
property to true
in your project's app config:
{
"ios": {
"usesAppleSignIn": true
}
}
在本地运行 EAS 构建 将使用 iOS 功能签名 在构建之前启用所需的功能。
¥Running EAS Build locally will use iOS capabilities signing to enable the required capabilities before building.
{
"expo": {
"plugins": ["expo-apple-authentication"]
}
}
不使用 EAS 构建 的应用必须为其打包标识符 手动配置 Apple 登录功能。
¥Apps that don't use EAS Build must manually configure the Apple Sign In capability for their bundle identifier.
如果你通过 苹果开发者控制台 启用 Apple 登录功能,请务必在 ios/[app]/[app].entitlements 文件中添加以下权利:
¥If you enable the Apple Sign In capability through the Apple Developer Console, then be sure to add the following entitlements in your ios/[app]/[app].entitlements file:
<key>com.apple.developer.applesignin</key>
<array>
<string>Default</string>
</array>
此外,在你的 ios/[app]/Info.plist 中将 CFBundleAllowMixedLocalizations
设置为 true
,以确保登录按钮使用设备语言环境。
¥Also, set CFBundleAllowMixedLocalizations
to true
in your ios/[app]/Info.plist to ensure the sign-in button uses the device locale.
¥Usage
import * as AppleAuthentication from 'expo-apple-authentication';
import { View, StyleSheet } from 'react-native';
export default function App() {
return (
<View style={styles.container}>
<AppleAuthentication.AppleAuthenticationButton
buttonType={AppleAuthentication.AppleAuthenticationButtonType.SIGN_IN}
buttonStyle={AppleAuthentication.AppleAuthenticationButtonStyle.BLACK}
cornerRadius={5}
style={styles.button}
onPress={async () => {
try {
const credential = await AppleAuthentication.signInAsync({
requestedScopes: [
AppleAuthentication.AppleAuthenticationScope.FULL_NAME,
AppleAuthentication.AppleAuthenticationScope.EMAIL,
],
});
// signed in
} catch (e) {
if (e.code === 'ERR_REQUEST_CANCELED') {
// handle that the user canceled the sign-in flow
} else {
// handle other errors
}
}
}}
/>
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
alignItems: 'center',
justifyContent: 'center',
},
button: {
width: 200,
height: 44,
},
});
¥Development and testing
你可以在 iOS 上的 Expo Go 中测试此库,而无需遵循上述任何说明。但是,如果你使用 EAS Build,则需要添加配置插件才能使用此库。当你登录 Expo Go 时,你收到的标识符和值可能与你在独立应用中收到的标识符和值不同。
¥You can test this library in Expo Go on iOS without following any of the instructions above. However, you'll need to add the config plugin to use this library if you are using EAS Build. When you sign into Expo Go, the identifiers and values you receive will likely be different than what you'll receive in standalone apps.
你可以在 iOS 模拟器上对该库进行有限的测试。但是,并非所有方法的行为都与在设备上的行为相同,因此我们强烈建议在开发时尽可能在真实设备上进行测试。
¥You can do limited testing of this library on the iOS Simulator. However, not all methods will behave the same as on a device, so we highly recommend testing on a real device when possible while developing.
¥Verifying the Response from Apple
Apple 的响应包括包含用户信息的签名 JWT。为了确保响应来自 Apple,你可以使用 Apple 的公钥(发布于 https://appleid.apple.com/auth/keys)对签名进行加密验证。这个过程并不是 Expo 特有的。
¥Apple's response includes a signed JWT with information about the user. To ensure that the response came from Apple, you can cryptographically verify the signature with Apple's public key, which is published at https://appleid.apple.com/auth/keys. This process is not specific to Expo.
import * as AppleAuthentication from 'expo-apple-authentication';
AppleAuthenticationButton
Type: React.Element<AppleAuthenticationButtonProps>
This component displays the proprietary "Sign In with Apple" / "Continue with Apple" button on your screen. The App Store Guidelines require you to use this component to start the authentication process instead of a custom button. Limited customization of the button is available via the provided properties.
You should only attempt to render this if AppleAuthentication.isAvailableAsync()
resolves to true
. This component will render nothing if it is not available, and you will get
a warning in development mode (__DEV__ === true
).
The properties of this component extend from View
; however, you should not attempt to set
backgroundColor
or borderRadius
with the style
property. This will not work and is against
the App Store Guidelines. Instead, you should use the buttonStyle
property to choose one of the
predefined color styles and the cornerRadius
property to change the border radius of the
button.
Make sure to attach height and width via the style props as without these styles, the button will not appear on the screen.
See: Apple Documentation for more details.
buttonStyle
Type: AppleAuthenticationButtonStyle
The Apple-defined color scheme to use to display the button.
buttonType
Type: AppleAuthenticationButtonType
The type of button text to display ("Sign In with Apple" vs. "Continue with Apple").
cornerRadius
Optional • Type: number
The border radius to use when rendering the button. This works similarly to
style.borderRadius
in other Views.
onPress
Type: () => void
The method to call when the user presses the button. You should call AppleAuthentication.signInAsync
in here.
style
Optional • Type: StyleProp<Omit<ViewStyle, 'backgroundColor' | 'borderRadius'>>
The custom style to apply to the button. Should not include backgroundColor
or borderRadius
properties.
AppleAuthentication.getCredentialStateAsync(user)
Name | Type | Description |
---|---|---|
user | string | The unique identifier for the user whose credential state you'd like to check.
This should come from the user field of an |
Queries the current state of a user credential, to determine if it is still valid or if it has been revoked.
Note: This method must be tested on a real device. On the iOS simulator it always throws an error.
A promise that fulfills with an AppleAuthenticationCredentialState
value depending on the state of the credential.
AppleAuthentication.isAvailableAsync()
Determine if the current device's operating system supports Apple authentication.
Promise<boolean>
A promise that fulfills with true
if the system supports Apple authentication, and false
otherwise.
AppleAuthentication.refreshAsync(options)
Name | Type | Description |
---|---|---|
options | AppleAuthenticationRefreshOptions | An |
An operation that refreshes the logged-in user’s credentials. Calling this method will show the sign in modal before actually refreshing the user credentials.
A promise that fulfills with an AppleAuthenticationCredential
object after a successful authentication, and rejects with ERR_REQUEST_CANCELED
if the user cancels the
refresh operation.
AppleAuthentication.signInAsync(options)
Name | Type | Description |
---|---|---|
options (optional) | AppleAuthenticationSignInOptions | An optional |
Sends a request to the operating system to initiate the Apple authentication flow, which will present a modal to the user over your app and allow them to sign in.
You can request access to the user's full name and email address in this method, which allows you to personalize your UI for signed in users. However, users can deny access to either or both of these options at runtime.
Additionally, you will only receive Apple Authentication Credentials the first time users sign
into your app, so you must store it for later use. It's best to store this information either
server-side, or using SecureStore, so that the data persists across app installs.
You can use AppleAuthenticationCredential.user
to identify
the user, since this remains the same for apps released by the same developer.
A promise that fulfills with an AppleAuthenticationCredential
object after a successful authentication, and rejects with ERR_REQUEST_CANCELED
if the user cancels the
sign-in operation.
AppleAuthentication.signOutAsync(options)
Name | Type | Description |
---|---|---|
options | AppleAuthenticationSignOutOptions | An |
An operation that ends the authenticated session. Calling this method will show the sign in modal before actually signing the user out.
It is not recommended to use this method to sign out the user as it works counterintuitively.
Instead of using this method it is recommended to simply clear all the user's data collected
from using signInAsync
or refreshAsync
methods.
A promise that fulfills with an AppleAuthenticationCredential
object after a successful authentication, and rejects with ERR_REQUEST_CANCELED
if the user cancels the
sign-out operation.
AppleAuthenticationCredential
The object type returned from a successful call to AppleAuthentication.signInAsync()
,
AppleAuthentication.refreshAsync()
, or AppleAuthentication.signOutAsync()
which contains all of the pertinent user and credential information.
See: Apple Documentation for more details.
Name | Type | Description |
---|---|---|
authorizationCode | string | null | A short-lived session token used by your app for proof of authorization when interacting with
the app's server counterpart. Unlike |
string | null | The user's email address. Might not be present if you didn't request the | |
fullName | AppleAuthenticationFullName | null | The user's name. May be |
identityToken | string | null | A JSON Web Token (JWT) that securely communicates information about the user to your app. |
realUserStatus | AppleAuthenticationUserDetectionStatus | A value that indicates whether the user appears to the system to be a real person. |
state | string | null | An arbitrary string that your app provided as |
user | string | An identifier associated with the authenticated user. You can use this to check if the user is still authenticated later. This is stable and can be shared across apps released under the same development team. The same user will have a different identifier for apps released by other developers. |
AppleAuthenticationFullName
An object representing the tokenized portions of the user's full name. Any of all of the fields
may be null
. Only applicable fields that the user has allowed your app to access will be nonnull.
Name | Type | Description |
---|---|---|
familyName | string | null | - |
givenName | string | null | - |
middleName | string | null | - |
namePrefix | string | null | - |
nameSuffix | string | null | - |
nickname | string | null | - |
AppleAuthenticationRefreshOptions
The options you can supply when making a call to AppleAuthentication.refreshAsync()
.
You must include the ID string of the user whose credentials you'd like to refresh.
See: Apple Documentation for more details.
Name | Type | Description |
---|---|---|
requestedScopes (optional) | AppleAuthenticationScope[] | Array of user information scopes to which your app is requesting access. Note that the user can
choose to deny your app access to any scope at the time of logging in. You will still need to
handle |
state (optional) | string | An arbitrary string that is returned unmodified in the corresponding credential after a successful authentication. This can be used to verify that the response was from the request you made and avoid replay attacks. More information on this property is available in the OAuth 2.0 protocol RFC6749. |
user | string | - |
AppleAuthenticationSignInOptions
The options you can supply when making a call to AppleAuthentication.signInAsync()
.
None of these options are required.
See: Apple Documentation for more details.
Name | Type | Description |
---|---|---|
nonce (optional) | string | An arbitrary string that is used to prevent replay attacks. See more information on this in the OpenID Connect specification. |
requestedScopes (optional) | AppleAuthenticationScope[] | Array of user information scopes to which your app is requesting access. Note that the user can
choose to deny your app access to any scope at the time of logging in. You will still need to
handle |
state (optional) | string | An arbitrary string that is returned unmodified in the corresponding credential after a successful authentication. This can be used to verify that the response was from the request you made and avoid replay attacks. More information on this property is available in the OAuth 2.0 protocol RFC6749. |
AppleAuthenticationSignOutOptions
The options you can supply when making a call to AppleAuthentication.signOutAsync()
.
You must include the ID string of the user to sign out.
See: Apple Documentation for more details.
Name | Type | Description |
---|---|---|
state (optional) | string | An arbitrary string that is returned unmodified in the corresponding credential after a successful authentication. This can be used to verify that the response was from the request you made and avoid replay attacks. More information on this property is available in the OAuth 2.0 protocol RFC6749. |
user | string | - |
Subscription
Name | Type | Description |
---|---|---|
remove | () => void | A method to unsubscribe the listener. |
AppleAuthenticationButtonStyle
An enum whose values control which pre-defined color scheme to use when rendering an AppleAuthenticationButton
.
AppleAuthenticationButtonStyle Values
WHITE_OUTLINE
AppleAuthenticationButtonStyle.WHITE_OUTLINE = 1
White button with a black outline and black text.
AppleAuthenticationButtonType
An enum whose values control which pre-defined text to use when rendering an AppleAuthenticationButton
.
AppleAuthenticationButtonType Values
AppleAuthenticationCredentialState
An enum whose values specify state of the credential when checked with AppleAuthentication.getCredentialStateAsync()
.
See: Apple Documentation for more details.
AppleAuthenticationCredentialState Values
REVOKED
AppleAuthenticationCredentialState.REVOKED = 0
AUTHORIZED
AppleAuthenticationCredentialState.AUTHORIZED = 1
NOT_FOUND
AppleAuthenticationCredentialState.NOT_FOUND = 2
TRANSFERRED
AppleAuthenticationCredentialState.TRANSFERRED = 3
AppleAuthenticationOperation
AppleAuthenticationOperation Values
IMPLICIT
AppleAuthenticationOperation.IMPLICIT = 0
An operation that depends on the particular kind of credential provider.
LOGIN
AppleAuthenticationOperation.LOGIN = 1
REFRESH
AppleAuthenticationOperation.REFRESH = 2
LOGOUT
AppleAuthenticationOperation.LOGOUT = 3
AppleAuthenticationScope
An enum whose values specify scopes you can request when calling AppleAuthentication.signInAsync()
.
Note that it is possible that you will not be granted all of the scopes which you request. You will still need to handle null values for any fields you request.
See: Apple Documentation for more details.
AppleAuthenticationScope Values
FULL_NAME
AppleAuthenticationScope.FULL_NAME = 0
EMAIL
AppleAuthenticationScope.EMAIL = 1
AppleAuthenticationUserDetectionStatus
An enum whose values specify the system's best guess for how likely the current user is a real person.
See: Apple Documentation for more details.
AppleAuthenticationUserDetectionStatus Values
UNSUPPORTED
AppleAuthenticationUserDetectionStatus.UNSUPPORTED = 0
The system does not support this determination and there is no data.
UNKNOWN
AppleAuthenticationUserDetectionStatus.UNKNOWN = 1
The system has not determined whether the user might be a real person.
LIKELY_REAL
AppleAuthenticationUserDetectionStatus.LIKELY_REAL = 2
The user appears to be a real person.
¥Error codes
大多数错误代码与官方 苹果授权错误 匹配。
¥Most of the error codes match the official Apple Authorization errors.
代码 | 描述 |
---|---|
错误 _ 无效 _ 操作 | 执行了无效的授权操作。 |
ERR_INVALID_RESPONSE | 授权请求收到无效响应。 |
ERR_INVALID_SCOPE | 传入了无效的 AppleAuthenticationScope 。 |
错误请求取消 | 用户取消了授权尝试。 |
错误请求失败 | 授权尝试失败。查看错误消息以获取更多信息。 |
ERR_REQUEST_NOT_HANDLED | 授权请求未得到正确处理。 |
ERR_REQUEST_NOT_INTERACTIVE | 授权请求不是交互式的。 |
ERR_REQUEST_UNKNOWN | 由于未知原因,授权尝试失败。 |