Peabody Compliance SDK

Integrate sub-second location integrity and hardware-backed device verification into your mobile and web applications.

Installation

The Peabody SDK for iOS is distributed as a Swift Package. You can add it to your project in Xcode by pointing to our release repository.

https://github.com/PeabodySecure/PeabodySDK-Release

Configuration

The Peabody SDK supports multiple authentication methods depending on your security architecture. Choose one of the following methods to initialize the SDK early in your app lifecycle (e.g., in AppDelegate or your main App struct).

Method 1: Hardcoded API Key

Use this method if you wish to bundle your API key directly within the application.

import PeabodySDK

Peabody.configure(apiKey: "your_api_key_here")

Method 2: Client ID Handshake (Recommended)

Use this method to exchange a public Client ID for a temporary session token. This avoids embedding your sensitive API key in the binary. You can configure this via code or Info.plist.

// Option A: Configure via code
Peabody.configure(clientId: "your_client_id_here")

// Option B: Add 'PeabodyClientID' to your Info.plist
// The SDK will automatically perform the handshake on the first verification.

Requesting Permissions

Peabody requires location permissions to perform jurisdictional checks. You can request "When In Use" or "Always" access using our helper methods.

Peabody.requestWhenInUsePermission { status in
    print("Location status: \(status)")
}

Customer Tracking

To accurately track and log end-user (retail player) activity in your Peabody Dashboard, it is required to provide a unique User ID and Email during every verification call. This allows you to audit specific users and detect multi-accounting or high-risk repeat offenders.

• External ID: Your internal database ID for the user (e.g., Player UUID or Username).
• External Email: The end-user's registered email address.

// Swift (iOS) Example
Peabody.verifyLocation(externalId: "user_123", externalEmail: "player@example.com") { result in
    // Handle result
}

Running Verification

To perform a check, call verifyLocation. This method automatically gathers GPS coordinates, IP intelligence, and device hardware signals. The response provides deep programmatic access to specific risk vectors.

// Swift (iOS)
Peabody.verifyLocation(
    externalId: "player_uuid_99",
    externalEmail: "player@domain.com"
) { result in
    switch result {
    case .success(let verdict):
        // 1. Direct Verdict
        if verdict.isCompliant {
            print("Access Granted. Risk Score: \(verdict.score)")
        }

        // 2. Programmatic Integrity Flags
        if verdict.isVPNOrProxyActive {
            print("Threat: VPN or Proxy Detected")
        }
        if verdict.isScreenCaptured {
            print("Threat: Screen Mirroring Active")
        }

        // 3. Location Metadata
        print("Device City: \(verdict.city)")
        print("IP Address: \(verdict.ipAddress)")
        
    case .failure(let error):
        print("Verification error: \(error.localizedDescription)")
    }
}

Hardware-Backed Integrity

The Peabody SDK utilizes Apple's App Attest service to prove that requests originate from a genuine, unmodified device. This is handled automatically during the verifyLocation flow.

• Cryptographic proof via Secure Enclave
• Automatic key rotation and registration
• Replay protection via stateless HMAC challenges

Android SDK

Integrate sub-second location integrity and Google Play Integrity verification into your Android applications.

Installation

The Peabody SDK for Android is distributed via Maven. To integrate it, add the dependency to your app-level build.gradle file and ensure your repository settings are configured.

Step 1: Add Dependency

// build.gradle
dependencies {
    implementation 'com.peabodycompliance:sdk-android:1.0.0'
}

Step 2: Repository Configuration

Ensure mavenCentral() is included in your settings.gradle or project-level build.gradle. If you are using a private repository, add the following:

// settings.gradle
dependencyResolutionManagement {
    repositories {
        mavenCentral()
        // Add custom repository if provided
    }
}

Configuration

Initialize the SDK early in your application lifecycle, typically in your MainActivity or Application class. You will need your Peabody API Key and Google Cloud Project Number.

// Kotlin
Peabody.configureWithApiKey(
    context = this, 
    apiKey = "your_api_key_here", 
    cloudProjectNumber = 350256575822L
)

Running Verification

Verify a user's location and device integrity by calling verifyLocation. The SDK handles permission checks, GPS acquisition, and Play Integrity token generation automatically.

// Kotlin
Peabody.verifyLocation(
    externalId = "user_abc_123",
    externalEmail = "player@email.com"
) { result ->
    result.onSuccess { verdict ->
        if (verdict.isCompliant) {
            // Access Granted
            Log.d("Peabody", "Verified: ${verdict.score}/100")
        }
    }.onFailure { error ->
        // Handle network or permission errors
    }
}

Play Console Linking

For hardware-backed integrity to function, you must link your Google Play Console to the Peabody Google Cloud Project. This allows our servers to cryptographically verify your app's tokens.

JavaScript SDK (Web)

Secure your web applications and sweepstakes sites using our browser-based trust layer.

Installation

You can integrate the Peabody Web SDK using our hosted CDN for immediate updates, or download the source for self-hosting.

Option 1: CDN (Recommended)

Include the Peabody script directly in your HTML <head>. This ensures you always have the latest security definitions.

<script src="https://peabodycompliance.com/resources/js/peabody.min.js"></script>

Option 2: Self-Hosting & GitHub

For organizations requiring full control over assets, you can download the script from our GitHub repository and host it on your own servers.

Configuration

Set your authentication after the script loads:

<script>
  Peabody.config.sessionToken = 'acquired_session_token';
</script>

Web Verification

Trigger a verification session when a user performs a high-value action. This will prompt the browser for location access and gather device telemetry.

async function checkUser() {
    // Required: Pass (PlayerID, PlayerEmail)
    const result = await Peabody.verifySession('user_123', 'player@email.com');
    
    if (result.compliant) {
        console.log("Verified. Risk Score: " + result.risk_score);
    } else {
        alert("Verification failed: " + result.reason);
    }
}

SDK Response Structure

The verification call returns a comprehensive object containing all trust signals. Whether using the iOS or JavaScript SDK, the underlying data structure is consistent.

{
  "status": "failure",
  "compliant": false,
  "risk_score": "100",
  "risk_level": "Critical",
  "reason": "Proxy/VPN detected; High distance discrepancy",
  "external_id": "user_12345",
  "device_integrity": {
    "hardware_integrity": true,
    "is_jailbroken": false,
    "is_mock_location": false,
    "is_screen_captured": false,
    "is_produced_by_accessory": false,
    "is_vpn_active": true
  },
  "location_validation": {
    "distance_km": 8167.31,
    "ip_country": "Poland"
  },
  "ip_intelligence": {
    "extensions": {
      "asn": "212238",
      "as": "DataCamp Limited"
    }
  },
  "metadata": {
    "lat": 30.2694,
    "lon": -81.3896,
    "ip": "149.102.244.98",
    "city": "Jacksonville Beach",
    "state": "FL",
    "country": "United States"
  },
  "timestamp": "2026-03-01 15:03:50"
}