Getting Started

SDK Requirements

Android Requirements:

Minimum SDK: API Level 26 (Android 8.0)
Target SDK: API Level 35 recommended
Java 8+ or Kotlin support

Permissions:

The SDK’s AAR declares every permission it needs and Android’s manifest merger adds them to your app automatically - you do not need to add any permissions manually. For transparency, the merged permissions are:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="com.android.keystore.CERTIFICATE_ACCESS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />
<uses-permission android:name="android.permission.HIDE_OVERLAY_WINDOWS" />

Note: the SDK deliberately does not declare QUERY_ALL_PACKAGES. Google Play rejects it for the security use case and it forces every integrator into a policy review. Package visibility is requested by generic intent through a <queries> block the SDK ships instead. Do not add it yourself.

Install the SDK

There are three ways to add the SDK. Pick one, then do Initialize the SDK and App and Build Registration below: those two steps are identical whichever install method you choose.

Option 1, the Alphyn CLI: one command wires everything. Recommended.
Option 2, from the registry by hand: you edit Gradle yourself and the registry still serves the AAR. Nothing is downloaded.
Option 3, offline: a self-contained AAR you download, for build machines that cannot reach the registry.

Option 1: Install with the Alphyn CLI (recommended)

alphyn-cli integrate --android-api-key <key> adds the SDK dependency, the initialization, and the build-registration hook for you, and wires the registry as a Maven repository. The SDK is fetched from the Alphyn package registry at build time, so set your app API key in the build environment first; see SDK Registry Access:

export ALPHYN_REGISTRY_KEY=<YOUR_APP_API_KEY>
alphyn-cli integrate --android-api-key <YOUR_APP_API_KEY>
alphyn-cli doctor

doctor reports every piece of the integration and names anything missing.

Option 2: Install from the registry, by hand (no CLI)

Do this when you want to wire Gradle yourself but still let the registry serve the AAR: nothing is downloaded, and your build stays on the exact version you pin. Each step below is one thing the CLI would otherwise do for you.

Before you start: register your Android app and generate its API key (see How to Register Your App).

Step 1. Put your API key in the build environment. The registry authenticates with your app API key. Export it wherever your build runs (your shell profile, an untracked env file, or a CI secret), and never commit it. See SDK Registry Access.

export ALPHYN_REGISTRY_KEY=<YOUR_APP_API_KEY>

Step 2. Add the Alphyn registry as a Maven repository. Newer projects list repositories in settings.gradle(.kts) under dependencyResolutionManagement; older projects use the root build.gradle. Add this authenticated Maven to whichever your project uses (the user is the literal x, the password is your key):

// settings.gradle.kts  ->  dependencyResolutionManagement { repositories { ... } }
maven {
    url = uri(System.getenv("ALPHYN_REGISTRY_URL") ?: "https://packages.byterialab.com/maven")
    credentials {
        username = "x"
        password = System.getenv("ALPHYN_REGISTRY_KEY") ?: ""
    }
}

Step 3. Add the SDK dependency. In your app module’s build.gradle(.kts):

dependencies {
    implementation("com.byterialab:alphyn-sdk:<version>")
}

Find the latest published <version> by asking the registry for its Maven metadata and reading the <release> value (the user is x, the password is your key):

curl -u "x:<YOUR_APP_API_KEY>" \
  https://packages.byterialab.com/maven/com/byterialab/alphyn-sdk/maven-metadata.xml

Expected result: a Gradle sync resolves com.byterialab:alphyn-sdk. If it fails with Could not find com.byterialab:alphyn-sdk:<version>, the key is not exported or the repository block is missing: recheck Steps 1 and 2.

Now continue with Initialize the SDK and App and Build Registration below.

Option 3: Install offline (downloaded AAR)

Use this when your build cannot reach the registry. The self-contained AAR carries the native libraries inside it and needs no registry key.

Step 1. Add the AAR. Download the Alphyn SDK AAR from your app’s SDK Downloads page in the Alphyn dashboard, place it under app/libs/, and reference it in your app’s build.gradle:

dependencies {
    implementation(files("libs/alphyn-sdk-<version>.aar"))
}

Step 2. Native libraries. The AAR ships arm64-v8a, armeabi-v7a, and x86_64, so no extra ABI configuration is needed. The SDK links its C++ runtime statically and ships no shared libc++_shared.so, so no pickFirst rule is required.

Now continue with Initialize the SDK and App and Build Registration below.

App and Build Registration (Required)

Alphyn is fail-closed: every build’s app hash must be registered with the Alphyn backend, and an unregistered build terminates at launch. Registration has two parts:

Register your app once at portal.byterialab.com with the exact package name, and generate an API key - see How to Register Your App.
Register every build’s hash with that API key. The Alphyn CLI installs a Gradle build hook that registers each APK automatically as it is built. Alternatively, run the provided post-action-android.sh <apk-path> <api-key> script after each signed build.

Important: The app hash is the SHA-256 of your app’s signing certificate, so it is the same for every build signed with the same key and changes only when you re-sign with a different one. Registering it once per signing key is therefore enough, but do not ship a build whose hash was never registered.

If you distribute through Play App Signing, Google re-signs your upload with its own key, so the installed app reports Google’s certificate rather than your upload key’s. Enroll that value once from the Play Console; see Play App Signing.

Quick Start Integration

Basic Integration Example:

public class MainActivity extends AppCompatActivity {
    private AlphynSecurityListener securityListener;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        // Create security listener
        createSecurityListener();

        // Initialize SDK
        try {
            AlphynSDK.initialize(this);
        } catch (IllegalArgumentException e) {
            Log.e("Byteria", "SDK initialization failed: " + e.getMessage());
        }
    }

    private void createSecurityListener() {
        securityListener = new AlphynSecurityListener() {
            @Override
            public void onSuccess(AlphynCallbackResult result) {
                Log.i("Byteria", "Success: " + result.getMessage());

                if (result.getOriginalEventType() == AlphynEventType.INIT_COMPLETE) {
                    Log.i("Byteria", "SDK initialized successfully");
                }
            }

            @Override
            public void onFailure(AlphynCallbackResult result) {
                Log.w("Byteria", "Failure: " + result.getMessage());
            }

            @Override
            public void onThreatDetected(AlphynCallbackResult result) {
                Log.w("Byteria", "Threat detected: " + result.getMessage());
                // Handle security threat
                handleSecurityThreat(result);
            }
        };

        AlphynSDK.addSecurityListener(securityListener);
    }

    private void handleSecurityThreat(AlphynCallbackResult result) {
        // Implement your threat response logic
        AlertDialog.Builder builder = new AlertDialog.Builder(this);
        builder.setTitle("Security Alert")
               .setMessage("A security threat has been detected.")
               .setPositiveButton("OK", null)
               .show();
    }

    @Override
    protected void onDestroy() {
        super.onDestroy();
        AlphynSDK.removeSecurityListener(securityListener);
    }
}

Getting Started

Table of Contents

Getting Started

SDK Requirements

Install the SDK

Option 1: Install with the Alphyn CLI (recommended)

Option 2: Install from the registry, by hand (no CLI)

Option 3: Install offline (downloaded AAR)

App and Build Registration (Required)

Quick Start Integration