Skip to content
  • unity
  • getting started
  • getting started

Getting Started

The Alphyn Unity SDK protects Android and iOS player builds with device attestation, security scanning, and threat detection. This page is a complete, end-to-end integration for a Unity project targeting both platforms; follow it top to bottom.

Requirements

Section titled “Requirements”
  • Unity 2020.3 or higher
  • Android: API Level 26+ (Android 8.0+); target architectures arm64-v8a, armeabi-v7a, x86_64
  • iOS: iOS 15.0 or higher; Xcode 15.0 or higher; arm64 (device), arm64 (Apple Silicon simulator)

Before you begin

Section titled “Before you begin”
  1. Register both apps. A Unity project that ships both platforms is two apps on the portal, one for Android and one for iOS, each with its own API key. On portal.byterialab.com, Apps → Register App for each platform and generate a key. See How to Register Your App.
  2. Export your registry key. The Android .aar resolves from the Alphyn package registry at build time; iOS needs no registry key, since its framework is bundled. Set the key in the build environment and never commit it; see SDK Registry Access:
Terminal window
export ALPHYN_REGISTRY_KEY=<YOUR_APP_API_KEY>

Install the SDK

Section titled “Install the SDK”
Section titled “Option A: the Alphyn CLI (recommended)”

Run from the Unity project root (the folder with ProjectSettings/):

Terminal window
alphyn-cli integrate --android-api-key <API_KEY>

It vendors the C# plugin under Assets/AlphynSDK, wires the Android SDK to resolve from the registry through your Custom Main Gradle Template (Assets/Plugins/Android/mainTemplate.gradle), places the iOS Alphyn.xcframework, and writes the post-build registration script. Then, in Player Settings > Publishing Settings, enable Custom Main Gradle Template (Unity only uses mainTemplate.gradle when this is on), and verify with alphyn-cli doctor.

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

Section titled “Option B: from the registry, by hand (no CLI)”

Add the com.byterialab.alphyn-sdk package through the Unity Package Manager. The package carries the C# and the iOS framework; the Android .aar resolves from the registry Maven, wired in Step 3.

Step 1. Add the Alphyn scoped registry to Packages/manifest.json:

{
  "scopedRegistries": [
    { "name": "Alphyn", "url": "https://packages.byterialab.com/npm", "scopes": ["com.byterialab"] }
  ],
  "dependencies": { "com.byterialab.alphyn-sdk": "<version>" }
}

Step 2. Authenticate the Package Manager through ~/.upmconfig.toml (the user is the literal x, the password is your app API key, base64-encoded together as x:KEY):

[npmAuth."https://packages.byterialab.com/npm"]
_auth = "<base64 of x:YOUR_APP_API_KEY>"
alwaysAuth = true

Generate the value with printf 'x:%s' "$ALPHYN_REGISTRY_KEY" | base64.

Step 3. Wire the Android registry Maven for the .aar. In Player Settings > Publishing Settings, enable Custom Main Gradle Template, and add the authenticated Maven to its repositories block:

// Assets/Plugins/Android/mainTemplate.gradle, inside allprojects { repositories { ... } }
maven {
    url 'https://packages.byterialab.com/maven'
    credentials { username 'x'; password System.getenv('ALPHYN_REGISTRY_KEY') ?: '' }
}

If your build cannot reach the registry, use the self-contained plugin instead (it carries both native binaries and needs no registry key): see Installation.

Build settings

Section titled “Build settings”
  • Android (Edit > Project Settings > Player > Android): set Minimum API Level to 26 or higher, and enable ARM64 and ARMv7 architectures.
  • iOS (Edit > Project Settings > Player > iOS): set Target minimum iOS Version to 15.0 or higher; the xcframework links automatically during build.

Initialize the SDK

Section titled “Initialize the SDK”

Call Initialize from a MonoBehaviour early in your first scene. The second argument is a development-only debug hash; always pass "" in production, and your app’s Portal debug hash during development:

using Byteria.SDK;
using UnityEngine;


public class GameInitializer : MonoBehaviour
{
    void Start()
    {
        AlphynSDK.OnInitialized += (success, message) =>
        {
            if (success) Debug.Log("Alphyn SDK ready");
            else Debug.LogError($"SDK init failed: {message}");
        };
        AlphynSDK.Initialize(30f, ""); // interval in SECONDS
    }
}

For reading scan results and verifying sensitive actions, see Quick Start.

Register every build

Section titled “Register every build”

Alphyn is fail-closed: an unregistered build fails attestation at runtime, with no build-time error. On the CLI path the post-build script handles this; by hand:

  • Android. A Unity Android player build is an ordinary APK, registered by the SHA-256 of its signing certificate (stable per signing key). The CLI’s post-build script runs the registration for you; see CLI: Unity for registering a specific build.
  • iOS. A Unity iOS build produces an Xcode project; register it through the Xcode post-action flow.

Unity Android runtime initialization is being finalized together with the SDK. After integrating, alphyn-cli doctor reports the current status, so you always know whether a build is ready.

Advanced

Section titled “Advanced”