Paketan
Paket backend & pemula
Salin halaman
Klien backend resmi Lia dan proyek starter aman untuk TypeScript, Python, PHP dan Go.
Klien server resmi untuk TypeScript/JavaScript, Python, PHP dan Go. Mereka memanggil server Lia yang sama secara aplikasi API. Kunci uji melihat catatan uji; kunci live memerlukan aplikasi live dan melihat catatan live.
#Bangun backend
npx @lia-labs/create-app@latest backendPilih Node.js HTTP atau Express, FastAPI atau Django, PHP HTTP, atau Go HTTP. Backend yang dihasilkan memverifikasi sesi pemain berdurasi pendek dan pembayaran, menyimpan inventaris SQLite dengan bukti unik, mengakui pengiriman setelah pemberian yang berhasil, dan membatalkan pengembalian dana sekali. Starter Node juga mencakup tantangan hadiah yang dikeluarkan server dan pemindaian pemulihan yang dibatasi dan berhalaman.
Token CLI tidak per mai meminta Anda untuk menempelkan rahasia ke argumen terminal atau menulisnya ke frontend. Atur LIA_SERVER_KEY dan LIA_WEBHOOK_SECRET di server Anda. Buat kontrak coins-100 produk dalam Lia Developers, lalu ubah pemetaan hak milik yang dikelola server untuk produk nyata Anda. Simpan data/ pada volume yang tahan lama. Untuk beberapa instance aplikasi, ganti penyimpanan SQLite contoh dengan basis data transaksional bersama. Konfigurasikan HTTPS dan batas laju yang spesifik untuk aplikasi di lingkungan produksi.
Contoh integrasi kerangka kerja disertakan untuk Express, Next.js App Router, Hono, FastAPI, Django dan Laravel. Adapter kerangka kerja tidak dapat menentukan permainan Anda'hak atau aturan anti-cheat; itu tetap merupakan kode aplikasi yang dimiliki server.
#Pasang ke backend yang sudah ada
| Bahasa | Paket / sumber | Pasang |
|---|---|---|
| JavaScript / TypeScript | @lia-labs/server | npm install @lia-labs/server |
| Python | lia-labs-server | pip install 'lia-labs-server @ git+https://github.com/The-Lia-Labs/lia-server-python.git@v0.1.0' |
| PHP | lia-labs/server | Tambahkan repositori perusahaan GitHub VCS di bawah ini, lalu composer require lia-labs/server:^0.1.0 |
| Go | github.com/The-Lia-Labs/lia-server-go | go get github.com/The-Lia-Labs/lia-server-go@v0.1.0 |
Python dapat diinstal dari sumber GitHub yang ditandai; saat ini belum terdaftar di PyPI. PHP dapat diinstal melalui Composer VCS; saat ini belum terdaftar di Packagist.
{"repositories":[{"type":"vcs","url":"https://github.com/The-Lia-Labs/lia-server-php"}]}Node mendukung ESM dan CommonJS dan mencakup jenis TypeScript. Python menyediakan LiaClient dan AsyncLiaClient. PHP memerlukan 8.2+ dan cURL; starter inventaris yang dihasilkan juga memerlukan PDO SQLite. Go'klien menggunakan perpustakaan standar; inventaris starter yang dihasilkannya menggunakan SQLite hingga CGO dan memerlukan kompiler C. Jangan impor paket-paket ini dalam bundle browser.
#Otentikasi pemain
import {LiaClient} from '@lia-labs/server';
const lia = new LiaClient(process.env.LIA_SERVER_KEY!);
const player = await lia.requireSession(sessionFromLia);
const {products} = await lia.listProducts();Python: lia.require_session(session); PHP: $lia->requireSession($session); Go: client.RequireSession(ctx, session).
Frontend mengirim sesi yang dikembalikan oleh Lia.init() atau Lia.session(), bukan pemain ID atau kunci server Anda. Hasilnya's exp adalah Unix milidetik. Klien memverifikasi respons'mode, bentuk pemain dan masa berlaku. Perbarui sesi frontend ketika berakhir. API itu sendiri memverifikasi tanda tangan dan kepemilikan aplikasi.
#Operasi
Kontrak yang dapat dibaca mesin bersama adalah operasi. Nama di bawah adalah nama TypeScript/PHP. Python menggunakan snake_case dan parameter kata kunci; Go menggunakan PascalCase, context.Context, lia.Params dan lia.RequestOptions.
| Area | Metode |
|---|---|
| Sesi | verifySession, requireSession |
| Katalog | listProducts |
| Pembelian | getCharge, deliverCharge, refundCharge, listPendingCharges |
| Hadiah LIA | payReward, getPool |
| Notifikasi | sendNotification |
| Iklan berhadiah | verifyAd, createAdChallenge, claimAdChallenge |
| Lobi multiplayer | listTables, saveTable, sitAtTable, removeTable |
| Skor yang otoritatif | listLeaderboards, saveLeaderboard, getLeaderboard, submitScore, moderateScore |
| Penyimpanan hanya server | getPlayerStorage, setPlayerStorage |
| Webhook | listWebhookEvents, replayWebhookEvent, verifikasi tanda tangan mentah dan konstruksi peristiwa |
| Analitik | getAnalytics, exportAnalytics |
Tulis penyimpanan memerlukan expectedVersion; konflik adalah HTTP 409. JSON null adalah nilai yang disimpan valid. Akses browser ke penyimpanan ini hanya dapat dibaca dan terikat dengan sesi'pemain. Skor harus berasal dari permainan yang divalidasi server; memindahkan skor yang tidak tepercaya ke endpoint server tidak membuatnya otoritatif.
#Pembelian dan pengulangan
- Ambil biaya dengan kunci server. Periksa
playerId,mode,productIddan sebuahpaid/deliveredstatus. - Dalam satu transaksi basis data, sisipkan bukti unik yang dikunci oleh mode + biaya ID dan berikan hak akses yang terpeta hanya jika struk baru.
- Komit inventaris, lalu panggil
deliverCharge. Ulangi pengakuan itu bahkan jika inventaris sudah diberikan. - Selaraskan tagihan yang belum dibayar menggunakan setiap halaman kursor. Refund harus diperiksa kembali terhadap Lia dan dibatalkan sekali di database Anda.
Semua klien menggunakan anggaran permintaan 15 detik dan maksimal dua ulang secara default. Mereka mengulang kesalahan HTTP/jaringan sementara, menghormati Retry-After, menolak redirect yang diautentikasi dan mengabaikan tubuh kesalahan mentah dari kesalahan. Mutasi mempertahankan Idempotency-Key yang sama dan tubuh yang diserialisasi dalam satu panggilan. Lewatkan kunci bisnis yang stabil saat mengulang panggilan setelah restart proses atau panggilan terpisah.
await lia.deliverCharge({id: charge.id}, {idempotencyKey: `deliver:${charge.id}`});Python menggunakan idempotency_key=...; PHP mengambilnya sebagai argumen kedua; Go menggunakan lia.RequestOptions{IdempotencyKey: ...}. Verifikasi sesi adalah POST gaya baca dan tidak menciptakan catatan idempotensi yang tidak perlu. LiaError mencakup kode, status HTTP, permintaan ID dan penundaan ulang. Jangan pernah memperlakukan 503 sebagai pemain yang tidak valid atau pembelian yang selesai. Verifikasi GETs dan sesi yang aman memiliki ulang yang terbatas; perilaku tepat sekali secara keuangan juga bergantung pada API'dan basis data Anda'penerimaan bisnis unik.
#Webhook yang ditandatangani
Verifikasi bytes mentah yang tidak berubah sebelum parsing JSON dengan constructWebhookEvent (Node), construct_webhook_event (Python), Webhooks::constructEvent (PHP), atau ConstructWebhookEvent (Pergi). Gunakan Lia-Signature header dan aplikasi Anda'rahasia webhook. Verifikasi menolak payload yang diubah dan timestamp yang lebih dari lima menit di masa lalu atau masa depan. Jenis peristiwa yang ditandatangani yang tidak diketahui dapat diakui tanpa memberikan apa pun; test:true probes tidak pernah memberikan inventaris.
Lia menyimpan kotak keluar yang tahan lama dengan peristiwa ID yang stabil. Ia mencoba pengiriman secara langsung, lalu setelah 1 menit, 5 menit, 30 menit, 2 jam, 8 jam, 24 jam, dan 48 jam. Setiap upaya mendapatkan tanda waktu tanda tangan yang baru. Periksa metadata menggunakan listWebhookEvents, dan ulang peristiwa setelah memperbaiki handler Anda. Deduplikasi dengan bukti bisnis yang stabil bahkan setelah ulang. Jangan kembalikan 2xx sebelum komitmen penyelesaian.
#Tantangan hadiah
Buat tantangan di server Anda dengan konteks yang dimiliki server dan pemain ID. Kembalikan challengeId ke frontend dan lewatkan sebagai rewardContextId saat meminta iklan yang diberi hadiah. Pemeriksaan bind/claim memeriksa pemain, mode aplikasi, format iklan, usia, penyelesaian, dan penggunaan ulang. Sebuah klaim tidak memberikan inventaris secara mandiri; berikan permainanmu'hak aksesnya sekali per iklan dalam transaksi Anda sendiri.
Hadiah bernilai tinggi memerlukan providerVerified:true. Alur bukti baru juga memerlukan host native Lia yang diperbarui untuk mengirimkan nonces per-iklan SSV dan callback AdMob SSV yang dikonfigurasi. Dukungan backend saja tidak meningkatkan aplikasi yang sudah terpasang. Penyelesaian native mode uji coba adalah bukti yang disimulasikan, bukan bukti yang ditandatangani penyedia nyata.
Iklan nyata di SDK Demo dibatasi 3 permintaan per hari UTC, dengan jeda minimal 30 menit. Pembelian dan hadiah LIA tetap disimulasikan. Perbarui Lia untuk menggunakan fitur ini.
#Analitik
Laporan mencakup pemain aktif harian, pembelian dan konversi pemain, telemetri iklan per format, dan retensi D1/D7/D30. CSV mencakup tipe catatan aktivitas, iklan, dan retensi. Pengumpulan retensi dimulai dengan rilis ini; kohort historis tidak dibuat. Cakupan iklan yang tidak lengkap mengembalikan metrik null. Pendapatan yang dilaporkan oleh SDK adalah estimasi, bukan pendapatan AdMob yang telah ditetapkan atau pernyataan pembayaran pengembang.
Kelola musim, sembunyikan atau pulihkan skor, periksa percobaan pengiriman webhook, dan kirim ulang peristiwa dari Lia Developers. Analitik mencakup aplikasi tim Anda dan ekspor CSV. Data pengujian dan produksi tetap terpisah.
#Validasi
Dari perusahaan lia-sdk repository:
npm install
python3 -m venv .venv
.venv/bin/pip install -e backends/python
LIA_PYTHON=.venv/bin/python npm run test:backends
npm run test:create-appPasang Postman CLI, PHP dengan cURL dan Go terlebih dahulu. Ini menjalankan semua empat klien nyata melalui simulasi Postman HTTP pihak pertama lokal, termasuk kegagalan sementara, mutasi berulang, kedaluwarsa sesi, redirect, tenggat waktu, dan manipulasi webhook. Ini tidak menyentuh data produksi. Lihat scripts/developer-server-features-local-test.mjs di repositori API untuk pengujian integrasi terpisah terhadap implementasi Worker lokal yang sebenarnya.
Diterjemahkan otomatis. Bahasa Inggris adalah sumber kebenaran. Baca dalam Bahasa Inggris