Getting Started with TesterPayKit
From your project account to your first bug report: create a project, add the SDK to your app, and triage what your testers find in the web console or from the terminal.
# Setup
1. Create an account
Create a customer account to manage your projects. Existing accounts can sign in to the web console. Tester registration is available separately from the sign-in page.
2. Create a project
Every app gets its own project, keyed by its bundle id. Create it in the web console, or with the
tpk CLI — the JSON output contains the project ID the SDK needs:
dart pub global activate tpk_cli tpk login tpk --json project create --name "My App" --bundle-id com.example.myapp
3. Install the SDK
Pick the SDK for your stack:
flutter pub add testerpaykit
npx expo install \ @testerpaykit/expo \ @react-native-async-storage/async-storage \ expo-sensors expo-device expo-application expo-file-system expo-audio
npm install @testerpaykit/react @testerpaykit/sdk @testerpaykit/api-client @testerpaykit/storage-browser
Early access: a Swift Package that is not on a public registry yet. Write to [email protected] and we send it to you.
4. Initialize with your project ID
Flutter: initialize before runApp and wrap your app, then run it with
flutter run --dart-define=TPK_PROJECT_ID=<project-uuid>.
import 'package:flutter/material.dart';
import 'package:testerpaykit/testerpaykit.dart';
final _navigatorKey = GlobalKey<NavigatorState>();
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
final tpk = await TesterPayKit.initialize(
config: TesterPayKitConfig(
projectId: const String.fromEnvironment('TPK_PROJECT_ID'),
apiBaseUrl: 'https://api.testerpaykit.com',
enableTesterMode: true,
),
);
runApp(MaterialApp(
navigatorKey: _navigatorKey,
// Screen views drive the testers' engaged minutes.
navigatorObservers: [tpk.navigatorObserver],
builder: (context, child) => TesterPayKitWrapper(
sdk: tpk,
navigatorKey: _navigatorKey,
child: child ?? const SizedBox.shrink(),
),
home: const HomeScreen(),
));
} Expo / React Native: initialize once and let testers report with a shake.
import { TpkExpo, useShake } from '@testerpaykit/expo';
import { useEffect, useState } from 'react';
export function App() {
const [tpk, setTpk] = useState<TpkExpo | null>(null);
useEffect(() => {
TpkExpo.init({
projectId: '<project-uuid>',
testerCode: '<tester-invite-code>',
}).then(setTpk);
}, []);
useShake({
enabled: !!tpk,
onShake: () => {
tpk?.submitBug({
title: 'Shake-reported bug',
description: 'Tester shook the device on the home screen.',
currentScreen: 'HomeScreen',
});
},
});
return null; // your real UI here
} Full setup, fail-safe init and all options: testerpaykit on pub.dev · @testerpaykit/expo on npm
# Bug Reports
How testers report
Testers join your project with an invite code you hand out from the web console. Inside your app they shake the device or tap the floating button, and file a report with:
- • A screenshot, annotated if they like
- • A screen recording
- • A spoken voice note instead of typing
What a report contains
- • From the tester: title, description, severity (critical, high, medium, low) and, if given, reproduction steps plus expected and actual behaviour
- • Device and app: device model, OS version, app version, build number and bundle id — added by the SDK
- • How they got there: the current screen and a trail of the screens and actions before the report
- • Crashes: captured by the SDK and filed as reports on their own
- • Attachments: screenshots, screen recordings and voice notes
Triage
Reports land in your project. Work through them in the web console, or list them from the terminal:
tpk bug list --severity critical --since 24h tpk bug get <bug-id>
# CLI & MCP
Install and log in
tpk is the TesterPayKit command line. tpk login opens
the web console in your browser; approve the request there. Every command supports
--json for scripts and agents.
dart pub global activate tpk_cli tpk login tpk project list
From bug report to fix
Hand a report to your AI coding tool, pull its attachments, and mark it fixed in a release:
tpk bug context <bug-id> # LLM-ready JSON for a fix prompt tpk bug download <bug-id> # screenshots, recordings, voice notes tpk bug fix <bug-id> --version 1.2.3
MCP server for AI agents
The CLI ships a second executable, tpk_mcp. It gives agents read-only access to your
sessions, timelines, bugs and bug context over the Model Context Protocol, using the session from
tpk login. For Claude Code:
claude mcp add tpk -- tpk_mcp
Ready to start?
Create a project account or look at the SDKs first. Additional testers require a separate availability check.