Payghaam
Get started

Documentation

Flutter SDK

Identify users, register push tokens, set tags, and track events from Flutter.

Prerequisites

  • Flutter ≥3.10.0, Dart ≥3.0.0
  • iOS 15.0+ / Android minSdk 21+
  • A Payghaam project and an SDK-type API key from the dashboard

Install

pubspec.yaml
dependencies:
  payghaam_flutter: ^0.1.0

Initialize & identify

dart
import 'package:payghaam_flutter/payghaam_flutter.dart';

await Payghaam.instance.initialize(PayghaamConfig(
  appId: 'YOUR_PROJECT_ID',
  apiKey: 'ek_client_...',          // SDK-type key from the dashboard
  baseUrl: 'https://api.yourhost.com',
));

await Payghaam.instance.login('your-backend-user-id');
await Payghaam.instance.user.addTag('plan', 'pro');
await Payghaam.instance.user.addEmail('[email protected]');
await Payghaam.instance.trackEvent('purchase', {'sku': 'sku_123'});

Push notifications

Push is native on both platforms from one plugin — iOS → APNs (no Firebase on iOS), Android → FCM. You do not add firebase_messaging to your app pubspec.

dart
final push = PayghaamPushProvider();
await Payghaam.instance.initialize(config, push: push);
await Payghaam.instance.login('user-id');
await Payghaam.instance.requestPushPermission();

// Terminated-state delivery receipts (iOS NSE + Android FCM service):
await push.shareConfig(
  appGroup: 'group.com.yourcompany.app.payghaam', // iOS only
  apiBase: config.baseUrl,
  apiKey: config.apiKey,
  externalId: 'user-id',
);
lightbulb

Tip

Don't call requestPushPermission() at launch — defer it until the user understands why they're being asked (e.g. after onboarding or a relevant in-app action), so the OS prompt lands with context instead of being reflexively dismissed.

Platform setup

  • iOS setup — capabilities, App Group, Notification Service Extension
  • Android setup — Firebase project, google-services.json, Gradle

Verify your integration

  1. Run the app on a device or simulator/emulator.
  2. Check the dashboard's Users list for a new subscriber after login() runs.
  3. Send a test push to that user from the dashboard composer.
  4. Confirm delivery and that tapping the notification opens the app.
  5. Set debug: true on PayghaamConfig for verbose SDK logging while you troubleshoot.

SDK → API mapping

SDK callEndpoint
login(id)POST /api/sdk/users
push / email / SMS registerPOST /api/sdk/users/:id/subscriptions
user.addTag(s)PUT /api/sdk/users/:id/tags
trackEventPOST /api/sdk/events
warning

Warning

If Identity Verification is enabled, pass identityHash to login(). Compute HMAC-SHA256 on your server — never ship the project secret in the app.