SDK FAQ

Question 1: Why does the checkEnvAvailable function return false?

Possible causes:

• The SIM card is not inserted.

• Mobile data is disabled.

• Network permissions are not granted.

Solution:

1. Check if a SIM card is inserted.

2. Check if mobile data is enabled.

3. Check the network permission configuration of the application.

Question 2: Why does the initialization interface checkEnvAvailableWithComplete always return NO?

Troubleshooting steps:

1. Check the SIM card status

   • The SIM card is activated and has no overdue payments.

   • Is mobile data enabled for the SIM card?

2. Check application permissions

   • Is network permission enabled for the app?

   • Android: Check if the application has both WLAN and mobile data network permissions.

3. Check the network environment

   • Does the device have a VPN agent?

   • When a VPN is enabled, one-click logon fails with the following errors:

     • China Unicom: Source IP error.

     • China Telecom: Error 800008.

     • China Mobile: Error 103111.

   • Solution: Disable the VPN, or enable and then disable airplane mode before you retry.

4. Check the configuration

   • Have you created a solution number in the Cloud console?

   • Does the Bundle ID for the build scheme match the one for your project?

   • The device time is set to the standard time. Do not change the phone's timestamp to an earlier or later time.

   • Did you call the setAuthSDKInfo API?

Question 3: When retrieving a phone number for the first time, the application network communication is normal, but phone number verification keeps failing. Why?

Possible causes:

• The SIM card has an overdue payment and cannot access the internet using mobile data.

• On some Android systems, WLAN and mobile data network permissions are managed separately. The application may have only WLAN permission and lack mobile data network permission.

Solution:

1. Check if the SIM card has an overdue payment and can access the internet using mobile data.

2. Android: Check if the application has both WLAN and mobile data network permissions.

Question 4: During one-click logon on a dual-SIM Android phone, which mobile data card is used for authentication?

The SIM card set as the default for mobile data is used for one-click logon authentication.

Question 5: Why does China Unicom 5G mobile data cause one-click logon to fail when retrieving the local phone number?

Solution:

Configure the China Unicom domain name enrichgw.10010.com in the networkSecurityConfig manifest file.

Configuration example:

<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">enrichgw.10010.com</domain>
    </domain-config>
</network-security-config>

Question 6: Can obtaining a logon token fail?

Failure cases:

• Occasional failures: These are caused by factors such as gateway disconnection due to network fluctuations, network unavailability, carrier server-side exceptions, or your business server-side exceptions.

• Persistent failures: These require assistance from the carrier to troubleshoot and resolve the issue.

Question 7: What network environments does the one-click logon service support?

• Recommended environments: 4G or 4G + Wi-Fi.

• Not recommended: The probability of interface request failure or timeout is higher on 2G and 3G networks.

Network environments supported by the three major carriers:

• China Mobile: 4G, 5G

• China Unicom: 4G, 5G (requires domain name configuration)

• China Telecom: 4G, 5G

Question 8: What should I do if timeouts occur frequently?

Troubleshooting steps:

1. Basic checks

   • Make sure the SIM card has no overdue payments.

   • Open a website in a browser to confirm that the mobile network is working correctly.

   • Confirm that the timeout period is set correctly. We recommend a value from 3000 ms to 5000 ms.

2. Possible causes

   • The probability of request failure or timeout is higher on 2G and 3G networks.

   • The probability of a timeout is higher during a network transition because of network instability.

Question 9: What are the common reasons for failing to obtain a token?

1. Network environment

   • Check the network settings on the phone. The success rate is higher on the 4G networks of the three major carriers.

   • The interface timeout period is too short. We recommend a value from 3000 ms to 5000 ms.

2. SIM card status

   • Check if the SIM card has an overdue payment.

   • Check the network settings to see if the device can access the internet using mobile data.

3. Network stability

   • When switching SIM cards, wait for the network to stabilize before you use the authentication and logon feature.

Question 10: What are the reasons for the "insecure mobile terminal" error with code 600005?

Possible causes:

• The phone's network is connected to a proxy.

• The phone is in a hooked state or has a related hook framework installed.

• The application is in an attached state.

• Is the phone rooted?

• Indicates whether the process is running in an emulator environment.

• The application is in debug mode. Use getReporter.setLoggerEnable(true) to disable this check.

Question 11: Under what circumstances is the "600005 illegal page modification" error returned?

The SDK returns the "600005 illegal page modification" error if you add a floating window control that obstructs the privacy policy, the one-click logon button, or the mask, or if you set the font color to transparent.

Question 12: Common error logs and solutions for failed one-click logon requests with a China Mobile card

networkSecurityConfig configuration example:

<application
    android:name=".DemoApplication"
    android:icon="@drawable/ic_launcher"
    android:label="@string/app_name"
    android:supportsRtl="true"
    android:theme="@style/AppTheme"
    android:usesCleartextTraffic="true"
    android:networkSecurityConfig="@xml/config"
    android:requestLegacyExternalStorage="true">
</application>

<!-- network-security-config.xml -->
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">enrichgw.10010.com</domain> <!-- China Unicom internal 5G request domain name -->
        <domain includeSubdomains="true">onekey.cmpassport.com</domain> <!-- China Mobile internal request domain name -->
    </domain-config>
</network-security-config>

Question 13: How do I resolve the crash "[UAReachability reachableType]: unrecognized selector sent to instance" that occurs with a China Mobile card?

Solution (iOS):

In your main project, click Project, select Edit Active Target > Build Settings > Linking > Other Linker Flags, and add -all_load and -ObjC.

Question 14: What should I do if I encounter permission-related issues?

Troubleshooting steps:

1. Check if the application can request permissions normally.

2. If you reference the AAR file correctly, the permissions are merged automatically.

3. If the permissions are not merged, you must manually add the following permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />

Question 15: What are the types of memory leaks and why do they occur?

1. Toast memory leak

• Cause 1: A Toast message is displayed when the one-click logon button is clicked without accepting the agreement, causing a memory leak when you exit the authorization page.

  • Solution: Use AuthUIConfig.setLogBtnToastHidden(true) to hide the default Toast message. Then, display your own Toast message based on the code of the click event.

• Cause 2: Illegal page modification. A Toast message "illegal page modification" is displayed if the number field, one-click logon button, and agreement text on the authorization page overlap or are obstructed when the one-click logon button is clicked.

  • Solution: Check the layers to resolve the overlap issue.

2. TokenResultListener memory leak

• Cause: The SDK internally holds the TokenResultListener that is set externally.

• Solution: After you finish using the one-click logon feature, set the callback to null using PhoneNumberAuthHelper.setAuthListener(null).

Question 18: How do I get the key for setAuthSDKInfo?

Steps to obtain the key:

1. Log on to the Phone Number Verification Service console.

2. In the navigation pane on the left, choose Phone Number Verification Service > Plan Management.

3. In the Actions column for the desired plan, click Key.

4. In the dialog box that appears, click Copy Key.

Important:

• This key is the application key for the phone number verification plan. It is not the AccessKey pair of your Alibaba Cloud account.

• We recommend that you maintain this key on your application server. This can reduce the risk of key leakage caused by security vulnerabilities on the client.

Question 19: How is security ensured when using the SDK?

The call process is secured by the carrier-grade operations and maintenance (O&M) security of carriers and Alibaba Cloud.

Security process:

1. Obtain an AccessCode (mobile client)

   • Initiate a request over the mobile data network to obtain an AccessCode.

   • An AccessCode is valid for one-time use and becomes invalid immediately after use.

   • AccessCode validity period:

     • China Mobile: 2 minutes

     • China Unicom: 60 minutes

     • China Telecom: 10 minutes

2. Verify the AccessCode (server-side)

   • Request the authentication result using the AccessCode and the phone number.

   • Authenticate server-side requests based on the Alibaba Cloud AccessKey pair.

Question 20: What network environments are supported?

Recommended environments:

• 4G network

• 4G + Wi-Fi hybrid network

• 5G network (note special carrier configurations)

Not recommended environments:

• 2G network: The probability of request failure or timeout is higher.

• 3G network: The probability of request failure or timeout is higher.

Carrier support:

• China Mobile: 4G, 5G

• China Unicom: 4G, 5G (5G requires configuration of the enrichgw.10010.com domain name)

• China Telecom: 4G, 5G

Question 21: How can I improve the stability and success rate of the SDK?

Best practices:

1. Network environment

   • Make sure to use the service in a 4G or 5G network environment.

   • Avoid using the service on 2G or 3G networks.

   • Avoid using the service during a network transition.

2. Device status

   • Make sure the SIM card is activated and has no overdue payments.

   • Make sure mobile data is enabled.

   • Disable VPN proxies.

   • Avoid using the service on emulators or rooted devices in a production environment.

3. Configuration optimization

   • Set a reasonable timeout period. We recommend a value from 3000 ms to 5000 ms.

   • Correctly configure network permissions.

   • Correctly configure networkSecurityConfig (Android).

   • Make sure the BundleID matches the configuration in the console.

4. Error handling

   • Implement a comprehensive error handling logic.

   • Retry failed operations. Note the validity period of the AccessCode.

   • Provide a fallback solution, such as text message verification.