# Playtesters — Full Documentation for AI Agents & Developers

Playtesters (https://playtesters.dev) is a collaborative closed-testing network and developer SDK suite designed to help Android developers meet Google Play's mandatory requirement of 20 opted-in testers for 14 continuous days.

---

## 1. Architecture Overview

- **Platform URL**: https://playtesters.dev
- **Web Dashboard**: https://app.playtesters.dev
- **Backend Ingest API**: https://api.playtesters.dev/v1
- **Domain for App Links / Deep Links**: https://playtesters.dev/invite/{code}

Playtesters operates on a reciprocal model: developers test other apps within their 20-tester group to earn credits, and spend credits to open campaigns for their own apps. No per-tester fees or marketplace middleman.

Real device verification is enforced through client-side SDKs that query the Google Play Install Referrer (`code=...&locale=...&playtesters=1`) upon first launch and report daily milestones back to the ingest endpoint with an API Key (`X-Api-Key`).

---

## 2. Official Client SDKs

### Flutter (`playtesters_sdk`)
- **Package**: https://pub.dev/packages/playtesters_sdk
- **Install**: `flutter pub add playtesters_sdk`
- **Setup**:
```dart
import 'package:flutter/material.dart';
import 'package:playtesters_sdk/playtesters_sdk.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Playtesters.configure(apiKey: 'ak_your_app_key');
  runApp(const MyApp());
}
```
- **Check Session & Bind Tester**:
```dart
// Call once in first screen initState / build:
await Playtesters.checkTestSession(context);
```
- **Log Milestone (Counts Test Day)**:
```dart
await Playtesters.achieved({'screen': 'onboarding_done'});
```
- **In-App Tester Status Badge (Optional)**:
```dart
const PlaytestersBadge();
```

---

### React Native (`@playtesters/react-native-sdk`)
- **Package**: https://www.npmjs.com/package/@playtesters/react-native-sdk
- **Install**:
```bash
npm install @playtesters/react-native-sdk @react-native-async-storage/async-storage react-native-device-info react-native-play-install-referrer
```
- **Setup**:
```tsx
import React, { useEffect } from 'react';
import { configure, PlaytestersAutoCheck, PlaytestersBadge, achieved } from '@playtesters/react-native-sdk';

export default function App() {
  useEffect(() => {
    configure({ apiKey: 'ak_your_app_key' });
  }, []);

  return (
    <>
      <PlaytestersAutoCheck />
      <PlaytestersBadge />
      <YourAppScreen />
    </>
  );
}
```
- **Log Milestone**:
```tsx
await achieved({ screen: 'completed_task' });
```

---

### Android Native Kotlin (`playtesters-sdk`)
- **Repository**: https://jitpack.io/#alexcao194/playtesters_sdk
- **Dependency**:
```kotlin
// settings.gradle.kts
repositories {
    mavenCentral()
    maven { url = uri("https://jitpack.io") }
}

// app/build.gradle.kts
dependencies {
    implementation("com.github.alexcao194:playtesters_sdk:v0.1.0")
}
```
- **Application.onCreate**:
```kotlin
Playtesters.configure(context = this, apiKey = "ak_your_app_key")
```
- **MainActivity.onCreate**:
```kotlin
Playtesters.checkTestSession(this)
```
- **Log Milestone**:
```kotlin
Playtesters.achieved(context, JSONObject().put("screen", "home")) { response ->
    Log.d("Playtesters", "Credited today: ${response.credited}")
}
```

---

## 3. Ingest HTTP API Specification

For custom or unsupported languages/frameworks, applications can communicate directly with the Ingest API:

- **Base URL**: `https://api.playtesters.dev/v1`
- **Authentication**: Header `X-Api-Key: <api_key>`

### Check App Config & Campaign Status
`GET /ingest/config`
- Response: `{"ok": true, "data": {"dialog_enabled": boolean}}`
- Returns `true` if the app currently has an active testing campaign.

### Bind Tester Session
`POST /ingest/bind`
- Body: `{"code": "123456", "device_id": "unique-device-identifier"}`
- Response: `{"ok": true, "data": {"tester_name": "alexcao"}}`

### Milestone Achievement (Counts 1 Test Day)
`POST /ingest/achieved`
- Body:
```json
{
  "code": "123456",
  "data": {"screen": "checkout"},
  "package": "com.example.app",
  "version_name": "1.0.0",
  "version_code": 1
}
```
- Response: `{"ok": true, "credited": true}`

### Pre-Launch Integration Verification
Call `POST /ingest/achieved` with empty code `{"code": "", "data": {}}` during local development to confirm the API key and mark the app as verified on the Playtesters dashboard.

---

## 4. Deep Links & Android App Links

- **Universal Invite URL**: `https://playtesters.dev/invite/{invite_code}`
- **AssetLinks Manifest**: `https://playtesters.dev/.well-known/assetlinks.json`
- **Apple App Site Association**: `https://playtesters.dev/.well-known/apple-app-site-association`
- **Ad Verification File**: `https://playtesters.dev/app-ads.txt`