Installation & Setup
Installation
npm install react-native-credentials-manager
# or if you prefer yarn
yarn add react-native-credentials-manager
# or with pnpm
pnpm add react-native-credentials-manager
Platform Requirements
Android
- Android 14+ (API level 34+) for full functionality
- Gradle plugin version 7.0+
- Gradle 7.0+
- AndroidX support
iOS
- iOS 16.0+
- Xcode 14.0+
- React Native 0.71.0+
Android Setup
To implement the Credential Manager API in your Android application, follow these steps:
1. Digital Asset Links Setup
To enable passkey support, you need to associate your Android app with your website by creating and hosting a Digital Asset Links JSON file.
Create a file named assetlinks.json
with the following content:
[
{
"relation": [
"delegate_permission/common.handle_all_urls",
"delegate_permission/common.get_login_creds"
],
"target": {
"namespace": "android_app",
"package_name": "your.package.name",
"sha256_cert_fingerprints": [
"YOUR_APP_SIGNING_CERTIFICATE_SHA256_FINGERPRINT"
]
}
}
]
Host this file at:
https://your-domain.com/.well-known/assetlinks.json
2. Get Your App's SHA-256 Certificate Fingerprint
To get your app's SHA-256 certificate fingerprint, you can use the following command:
For Debug Build:
cd android && ./gradlew signingReport
Look for the SHA-256 fingerprint in the "debugAndroidTest" variant.
For Release Build:
If you're using a keystore file for signing your release builds:
keytool -list -v -keystore your-keystore.keystore -alias your-key-alias
Replace your-keystore.keystore
and your-key-alias
with your actual keystore file path and alias.
3. Manifest Configuration
No additional manifest configuration is required for basic functionality. The library automatically sets up the necessary AndroidX Credential Manager dependencies.
4. ProGuard Configuration
If you're using ProGuard in your Android application, add these rules to your android/app/proguard-rules.pro
:
-if class androidx.credentials.CredentialManager
-keep class androidx.credentials.playservices.** {
*;
}
iOS Setup
To implement Authentication Services in your iOS application, follow these steps:
1. Add Associated Domains Capability
- In Xcode, select your project
- Go to the "Signing & Capabilities" tab
- Click "+" and add "Associated Domains"
- Add your domain with the
webcredentials
service:webcredentials:yourdomain.com
2. Create Apple App Site Association (AASA) File
Create a file named apple-app-site-association
(no file extension) with the following content:
{
"webcredentials": {
"apps": ["TEAMID.com.yourcompany.yourapp"]
}
}
Replace TEAMID
with your Apple Developer Team ID and com.yourcompany.yourapp
with your app's bundle identifier.
Host this file at:
https://yourdomain.com/.well-known/apple-app-site-association
3. Configure Sign In with Apple (Optional)
If you plan to use Apple Sign In:
- In Xcode, add the "Sign In with Apple" capability
- In your Apple Developer account:
- Go to "Certificates, Identifiers & Profiles"
- Select your app identifier
- Enable "Sign In with Apple"
- Configure the domains you want to use with Sign In with Apple
4. Info.plist Entries
No additional Info.plist entries are required as the library automatically configures the necessary entries for Authentication Services.
Google Sign-In Setup (For Android)
If you plan to use Google Sign-In on Android, follow these steps:
- Go to the Google Cloud Console
- Create a new project or select an existing one
- Click on "APIs & Services"
- Navigate to "Credentials" in the left sidebar
- Click "Create Credentials" and select "OAuth client ID"
- Choose "Android" as the application type
- Enter your Android package name (e.g., com.example.app)
- Add your application's SHA-1 signing certificate fingerprint:
Run this command in your project directory to get your SHA-1 key
cd android && ./gradlew signingReport
- Click "Create" to generate your Android OAuth client ID
- Take note of this Android OAuth client ID as you'll need it for your React Native app
- Ensure your configuration in the Google Cloud Console matches your app's package name and signing certificate
Important Requirements
For Android Digital Asset Links:
- The MIME type must be
application/json
- If you have a
robots.txt
, ensure it allows access to/.well-known/assetlinks.json
:User-agent: *
Allow: /.well-known/ - The domain must be fully-qualified
- Don't include trailing slashes or paths in the domain
- Subdomains are not automatically included in the association
For iOS Apple App Site Association:
- The file must be served without a file extension
- The MIME type must be
application/json
- The file must be accessible via HTTPS
- The file must be served directly (not redirected)
- If you have a
robots.txt
, ensure it allows access to/.well-known/apple-app-site-association
- Your server should allow HTTP/2 for optimal performance
Troubleshooting
Common Issues
Android Issues
-
Passkeys Not Working
- Ensure your
assetlinks.json
file is accessible via HTTPS - Verify the SHA-256 fingerprint matches your app's signing certificate
- Check that the package name matches your Android app exactly
- Confirm the domain matches exactly what's specified in your passkey requests
- Ensure your
-
ProGuard Issues
- Make sure the ProGuard rules are properly added
- Clean and rebuild your project after adding the rules
-
Google Sign-In Failed [Error: no credentials available]
- This error typically occurs when attempting to use Google Sign-In on an emulator without any Google accounts configured
- To resolve this:
- Ensure there is a Google account added to your device or emulator
- Verify that you have called the
signUpWithGoogle()
function before callingsignIn()
with'google-signin'
as an option - If testing on an emulator, consider using a physical device with Google accounts properly set up
iOS Issues
-
Passkeys Not Working on iOS
- Verify your Associated Domains capability is properly configured
- Ensure your AASA file is correctly set up and accessible
- Check that the domain in your passkey requests matches your associated domain
- Confirm you're using iOS 16.0+ for testing
-
Apple Sign In Not Working
- Verify the Sign In with Apple capability is added to your app
- Ensure your Apple Developer account has Sign In with Apple enabled for your App ID
- Check for any error messages in the Xcode console
Validation Tools
-
Android Asset Links Validator:
- Use the Asset Links Validator to verify your Digital Asset Links configuration
-
Apple App Site Association Validator:
- Use the Apple App Site Association Validator to verify your AASA configuration
Build Errors
If you encounter build errors:
-
Ensure you're using compatible versions of React Native and other dependencies
-
Clean the project and rebuild:
# For Android
cd android && ./gradlew clean
# For iOS
cd ios && pod install
For additional help, please check the GitHub issues or create a new issue if you encounter any problems.