Server Communication

All app-server protocols: handshake sync, in-app purchases, and event logging

Endpoints

Endpoint	Purpose	Auth
/functions/v1/handshake	Content sync, user data, manifest	JWT Bearer
/functions/v1/validate_purchase	Course & subscription IAP validation	JWT Bearer
/functions/v1/validate_purchase_ai_credits	AI credits IAP validation	JWT Bearer
/functions/v1/app_logs	Event logging	JWT Bearer

All endpoints authenticate via JWT. User ID is extracted from the token — never sent in the payload.

Handshake Sync Flow

Flutter App

Build payload

→

JWT + checksums

Handshake

Edge Function

→

manifest

Sync Orchestrator

ADD / UPDATE / DELETE

→

files

Cloudflare R2

CDN delivery

Speed test — 3 tests via Cloudflare CDN, min 1.5 Mbps avg

↓

Handshake — send analytics + device_id + pending purchases

↓

Manifest — server returns json_manifest, ai_usage, subscription

↓

Progressive sync — ADD new courses (with user confirm), UPDATE changed, DELETE removed

In-App Purchase Flows

Course Purchase

Consumable
Subscription-gated, uses download slots (2 for premium)

Subscription

Non-consumable
Monthly premium access

AI Credits

Consumable
Adds credits to user bank

Store purchase — Google Play / App Store native dialog

↓

Get receipt — Android: purchase_token | iOS: receipt_data via method channel

↓

Server validate — /validate_purchase verifies with Google/Apple API

↓

Acknowledge — completePurchase() ONLY after server confirms

Deferred Acknowledgment

Purchases are NOT acknowledged until the server validates the receipt. If validation fails, the purchase stays unacknowledged and Google/Apple auto-refunds after 3 days.

Product IDs

Product	Android	iOS
Course (e.g. H01ENB)	h01enb	me.hypnoelp.app.h01enb
Subscription	hypnoelp_subscriptions	me.hypnoelp.app.subscription_1month
AI Credits (4K)	ai_credits_4000	me.hypnoelp.app.ai_credits_4000
AI Credits (10K)	ai_credits_10000	me.hypnoelp.app.ai_credits_10000
Custom Audio	x99enb	me.hypnoelp.app.x99enb

Platform Support

Feature	Android	iOS
Course Purchase	Google Play Billing	StoreKit
Subscription	Multi-plan	Monthly only
AI Credits	Consumable	Consumable
Upgrade/Downgrade	With proration	N/A (single plan)
Free Trial	Pricing phases	App Store managed
Receipt Source	serverVerificationData	Method channel (app_receipt)

Event Logging

Logs sent to /functions/v1/app_logs with user_id, log_type, message, origin, and timestamp.

sync_module

Speed tests, sync status, download failures

billing

Purchase initiated, validated, failed

authentication

audio_playback

Audio player events

ai_chat

AI chatbot usage

user_report

User-reported issues

Checksum Requirements

Requirement	Value
JSON formatting	4-space indentation
Line endings	CRLF (\r\n)
Field order	LinkedHashMap (preserves server order)
Hash algorithm	MD5 of raw file bytes

Detailed docs: Handshake & Sync | Course Purchase | Subscriptions | AI Credits | Event Logging

Back to Hypnoelp App