Troubleshooting

iOS

Clear and reinstall pods if the native module does not build:

cd ios
pod deintegrate
pod install

Check these items if initialization fails:

• AlphynSDK.register() is called in AppDelegate before the React Native bridge starts.
• BGTaskSchedulerPermittedIdentifiers contains com.byterialab.backgroundcheck.
• UIBackgroundModes contains fetch.
• The app was reinstalled after Info.plist or background-task changes.

Android

Run alphyn-cli doctor first. It checks every part of the integration and names the missing one, which is faster than working through this list.

The build fails with Could not find com.byterialab:alphyn-sdk

> Could not resolve all dependencies for configuration ':app:debugCompileClasspath'.
   > Could not find com.byterialab:alphyn-sdk:<version>.
     Required by:
         project ':app' > project :alphyn_react-native-sdk

The authenticated Alphyn registry repository is not registered in the Android root build script, or ALPHYN_REGISTRY_KEY is not set in the build environment. React Native resolves from project-level repositories, so the SDK module’s own repository does not reach :app. Add the block shown in Platform Setup and export ALPHYN_REGISTRY_KEY (see SDK Registry Access), or re-run alphyn-cli integrate.

The app builds and runs, but nothing reaches the dashboard

The SDK never initialized, or the build was never registered.

• Filter logcat on Alphyn. Total silence means AlphynSDK.initialize() never ran: check that the call is present in your JS entry point and is not behind a Platform.OS guard.
• Confirm the Gradle build hook is installed in android/app/build.gradle, or register the build explicitly with alphyn-cli register --apk <path>. An unregistered build fails attestation at runtime with no build-time error.

Other checks

• minSdkVersion is at least 26.
• Clean the build if the native module or AAR integration is stale:

cd android
./gradlew clean

You do not need to add permissions or R8 keep rules yourself. The SDK ships both and they merge into your app automatically; see Platform Setup.

Event Listeners

If you are not receiving events:

• Make sure the SDK is initialized before registering listeners.
• On iOS, use addSecurityListener() and verify native startup registration is correct.
• On Android, use either addSecurityListener() or securityEvents() depending on whether you want dedicated or shared listeners.
• Clean up old subscriptions to avoid duplicated callbacks.

Error Handling

All SDK methods may throw AlphynError. Always wrap SDK calls in try-catch blocks.

import { AlphynError, AlphynErrorCode, AlphynSDK } from '@alphyn/react-native-sdk';

try {
  await AlphynSDK.initialize({ scanInterval: 5 });
} catch (error) {
  if (AlphynError.isAlphynError(error)) {
    switch (error.code) {
      case AlphynErrorCode.ARG_ERROR:
        console.error('Argument error:', error.message);
        break;
      case AlphynErrorCode.INIT_FAILED:
        console.error('Initialization failed:', error.message);
        break;
      case AlphynErrorCode.NOT_INITIALIZED:
        console.error('SDK not initialized');
        break;
      default:
        console.error('Unexpected Alphyn error:', error.message);
    }
  }
}

Common Error Codes

Code	Meaning
ARG_ERROR	Invalid argument such as an interval below the supported minimum
INIT_FAILED	SDK initialization failed
NOT_INITIALIZED	A method was called before initialization
SECURITY_VIOLATION	A threat or security violation was detected
NETWORK_ERROR	A network or backend request failed
NOT_SUPPORTED	The method is not available on the current platform
UNKNOWN	Any unmapped or unexpected error