Skip to main content

Mobile App Integration

Integrate Loyalteez rewards into your iOS, Android, or React Native mobile app using our REST API.

Overview​

Mobile apps integrate via direct HTTP API calls to our Cloudflare Workers. This approach works for all mobile platforms—no native SDK required.

Mobile Architecture​

Integration Options​

  • Uses Expo or React Native CLI
  • Privy SDK available
  • Similar to web React integration
  • See: React Native Guide

2. Native iOS​

  • Swift or Objective-C
  • URLSession for API calls
  • Privy iOS SDK
  • See: iOS Guide

3. Native Android​

  • Kotlin or Java
  • Retrofit or OkHttp for API calls
  • Privy Android SDK
  • See: Android Guide

4. Flutter​

  • Dart language
  • http package for API calls
  • Custom Privy integration
  • See: Flutter Guide

Key Differences from Web​

FeatureWebMobile
SDKJavaScript CDNDirect API calls
AuthenticationPrivy Web SDKPrivy Mobile SDK
Event TrackingAuto-detectionManual calls
WalletBrowser extensionIn-app wallet (Privy)
Push NotificationsNot availablePush for rewards
OfflineLimitedQueue events
Deep LinkingURLsApp scheme

Core Integration Steps​

Step 1: Set Up Authentication​

Mobile apps use Privy Mobile SDK for authentication:

iOS: CocoaPods or SPM
Android: Gradle
React Native: npm package

Step 2: Track Events via API​

Make HTTP POST requests to track user actions:

POST https://api.loyalteez.app/loyalteez-api/manual-event
Content-Type: application/json

{
  "event": "account_creation",
  "email": "[email protected]",
  "metadata": {
    "platform": "mobile",
    "os": "iOS"
  }
}

Step 3: Enable Gasless Transactions​

For perk claims, use the Gas Relayer:

POST https://relayer.loyalteez.app/relay
Authorization: Bearer PRIVY_ACCESS_TOKEN
Content-Type: application/json

{
  "to": "0x6ae30d6Dcf3e75456B6582b057f1Bf98A90F2CA0",
  "data": "0x...",
  "userAddress": "0x..."
}

Mobile-Specific Features​

1. Push Notifications​

Notify users when they earn rewards:

// When LTZ distributed
{
  "title": "You earned 100 LTZ!",
  "body": "Complete your profile to earn more",
  "data": {
    "type": "reward",
    "amount": 100,
    "txHash": "0x..."
  }
}

2. Deep Linking​

Link directly to wallet or perks:

loyalteez://wallet
loyalteez://perk/123
loyalteez://claim/456

3. Offline Event Queueing​

Queue events when offline, sync when online:

// Pseudocode
if (isOnline) {
  sendEvent(event);
} else {
  queueEvent(event);
  // Sync later when online
}

4. Biometric Authentication​

Use Face ID / Touch ID for secure transactions:

// iOS example
LocalAuthentication.authenticate() { success in
  if success {
    executeTransaction()
  }
}

Common Use Cases​

1. Social App​

  • Track profile creation → 100 LTZ
  • Track post creation → 10 LTZ
  • Track friend referral → 500 LTZ
  • Enable perk claims (premium features)

2. E-commerce App​

  • Track account signup → 50 LTZ
  • Track first purchase → 200 LTZ
  • Track purchases → 1 LTZ per $1
  • Enable perk redemption (discounts)

3. Gaming App​

  • Track level completion → 25 LTZ
  • Track daily login → 5 LTZ
  • Track achievement → 50 LTZ
  • Enable perk claims (power-ups)

4. Fitness App​

  • Track workout completion → 20 LTZ
  • Track goal achievement → 100 LTZ
  • Track streak milestone → 50 LTZ
  • Enable perk claims (premium features)

Best Practices​

✅ Do This​

  1. Queue events offline - Don't lose data
  2. Add retry logic - Handle network failures
  3. Use Privy for wallets - No wallet complexity
  4. Show rewards in-app - "You earned X LTZ!"
  5. Add push notifications - Increase engagement
  6. Use deep linking - Easy navigation
  7. Cache wallet address - Reduce API calls
  8. Handle errors gracefully - Good UX

❌ Avoid This​

  1. Don't spam events - Rate limits exist
  2. Don't expose API keys - Use environment variables
  3. Don't skip auth - Gas relayer requires Privy token
  4. Don't hardcode URLs - Use config files
  5. Don't ignore offline - Queue events
  6. Don't skip error handling - Apps crash

API Endpoints for Mobile​

EndpointMethodPurpose
/loyalteez-api/manual-eventPOSTTrack user events
/loyalteez-api/debugGETHealth check
/relayPOSTGasless transactions

Base URLs:

  • Event Handler: https://api.loyalteez.app
  • Gas Relayer: https://relayer.loyalteez.app

Authentication Flow​

Network Configuration​

All mobile apps connect to Soneium Mainnet:

{
  "chainId": 1868,
  "rpcUrl": "https://rpc.soneium.org",
  "blockExplorer": "https://soneium.blockscout.com",
  "contracts": {
    "loyalteez": "0x5242b6DB88A72752ac5a54cFe6A7DB8244d743c9",
    "perkNFT": "0x6ae30d6Dcf3e75456B6582b057f1Bf98A90F2CA0",
    "pointsSale": "0x5269B83F6A4E31bEdFDf5329DC052FBb661e3c72"
  }
}

Testing Your Integration​

1. Test Event Tracking​

# Use your mobile app or curl to test
curl -X POST https://api.loyalteez.app/loyalteez-api/manual-event \
  -H "Content-Type: application/json" \
  -d '{
    "event": "test_mobile_event",
    "email": "[email protected]",
    "metadata": {
      "platform": "mobile",
      "os": "iOS",
      "version": "1.0.0"
    }
  }'

2. Check Partner Portal​

Go to partners.loyalteez.app/analytics to see:

  • Events received
  • LTZ distributed
  • Active users

3. Test Gasless Transactions​

Make sure Privy authentication works and gas relayer accepts requests.

Performance Tips​

  1. Batch events - Send multiple events in one request (if supported)
  2. Cache aggressively - Wallet address, user data
  3. Use compression - gzip requests if possible
  4. Timeout wisely - 30s for events, 60s for transactions
  5. Monitor network - Detect offline early

Security Considerations​

  1. Store tokens securely - Use Keychain (iOS) / KeyStore (Android)
  2. Use HTTPS only - Never use HTTP
  3. Validate responses - Check server responses
  4. Rate limit locally - Don't spam your own app
  5. Obfuscate code - Protect API keys in prod builds

Support​

Next Steps​

Choose your platform:

Recommended: Start with React Native for faster development across both platforms.

Last updated on