# Playmez embed SDK

Everything a partner needs to put one Playmez game in a website or app. Every file here is
served from `https://playmez.com/sdk/…` and meant to be copied into your project as is.
The full guide, events and security rules: `partners.md` in this folder. Code for every game on every platform, with copy buttons: https://playmez.com/developers.

## Packages (preferred)

| Platform | Install |
| --- | --- |
| Website, React | `npm install playmez-embed` |
| React Native, Expo | `npm install playmez-embed-react-native react-native-webview` |
| Flutter | `flutter pub add playmez_embed` |
| Android | `implementation("com.github.playmez:playmez-android:2.0.0")` via https://jitpack.io |
| iOS | Swift Package `https://github.com/playmez/playmez-swift` |

## Drop-in files (generated from the packages)

| Platform | File | Needs |
| --- | --- | --- |
| Any website | `playmez.js` (+ `playmez.d.ts` types) | one `<script>` tag |
| React / Next.js / Vite | `react/PlaymezGame.tsx` | React 17+ |
| React Native / Expo | `react-native/PlaymezGame.tsx` | `react-native-webview` |
| Flutter (iOS + Android) | `flutter/playmez_game.dart` | `webview_flutter`, `webview_flutter_android`, `webview_flutter_wkwebview` |
| Android (Kotlin) | `android/PlaymezGameView.kt` | `INTERNET` permission |
| iOS (UIKit + SwiftUI) | `ios/PlaymezGameView.swift` | iOS 14+ |
| Your backend | `server/launch.mjs`, `server/launch.py`, `server/launch.php` | your API key |
| Your backend, hearing back | `server/verify-webhook.mjs`, `server/verify_webhook.py` | your webhook secret |
| API reference | `openapi.yaml` | |
| Try it | `demo.html` | a partner key |

## Three steps, every platform

1. **Your server** calls `POST /partner/launch` with `X-Api-Key` and your user's id. It gets a
   one-time launch URL, valid for five minutes. The key never leaves your server.
2. **Your page or app** opens that URL with the file for its platform (an iframe or a WebView).
3. The game posts events: `ready`, `result` (`game`, `won`, `net`), `close`, `error`
   (`code`, `message`). On `close`, hide or remove the frame.

**Portal.** Partners manage keys, origins, switches, webhooks, members and read usage at
https://playmez.com/partners (owner and developer roles; details in `partners.md`).

**Languages.** `lang` on a launch (`en`, `hi`) or a partner default; the embed renders in that language from its
first paint. Details in `partners.md`.

**Appearance.** Your accent, background, text, corners and font apply to the embed's first paint; set them in
the portal or per launch with `theme`. Details in `partners.md`.

**Webhooks.** `PUT /partner/webhook { url }` and Playmez posts `player.created`, `session.opened`,
`player.result` and `table.closed` to your server, signed with HMAC-SHA256 (`Playmez-Signature`) and
retried for a day. Verify with the `server/verify-webhook.*` files; details in `partners.md`.

Games: `ludo`, `callbreak`, `rummy`, `tambola`, `chess`, `teen_patti`, `carrom`, `roulette`, `crash`,
`trivia`, `wheel`, `scratch`. Players play alone against the computer or at a private table.
Points are virtual, non-transferable and worth nothing.