RevenueCat ve Credit Packages Konfigürasyon Rehberi

Bu dokümantasyon, Allmine API projesinde RevenueCat ile kredi paketleri sisteminin konfigürasyonunu adım adım açıklar.

İçindekiler

1. Genel Bakış
2. RevenueCat Konfigürasyonu
3. Credit Packages Konfigürasyonu
4. Environment Variables Referansı
5. Store Type Eşleştirmesi
6. Product ID vs Store Identifier
7. Konfigürasyon Kontrol Listesi
8. Sorun Giderme

Genel Bakış

Sistem, RevenueCat API v2 üzerinden satın alma işlemlerini yönetir ve webhook ile gelen purchase event'lerini işleyerek kullanıcılara otomatik kredi ekler.

[Mobil Uygulama] → [App Store / Play Store] → [RevenueCat] → [Webhook] → [Allmine API] → [MongoDB]

Mimari Özeti

RevenueCat Konfigürasyonu

1. RevenueCat Hesap ve Proje Kurulumu

1. RevenueCat üzerinden hesap oluşturun
2. Yeni proje oluşturun
3. Project Settings → Project ID'yi kopyalayın (proj_xxxxxxxxxxxxx formatında)

2. API Key Oluşturma

1. RevenueCat Dashboard → Project Settings → API Keys
2. "New" butonuna tıklayın
3. Version: V2 seçin
4. Gerekli izinler:
   • project_configuration:products:read_write
   • project_configuration:apps:read
   • customer_information:customers:read
5. Secret Key'i kopyalayın ve güvenli saklayın (sadece bir kez gösterilir)

3. App ID'leri Alma

Her store tipi için ayrı App ID gerekir:

4. Webhook Konfigürasyonu

1. Project Settings → Webhooks → Add Webhook
2. URL: https://your-domain.com/api/revenuecat/webhook
3. Authentication: Bearer token ile REVENUECAT_WEBHOOK_SECRET kullanılır
4. Events: En azından şunları seçin:
   • INITIAL_PURCHASE (zorunlu)
   • NON_RENEWING_PURCHASE (kredi paketleri için)

Not: RevenueCat webhook isteklerinde Authorization: Bearer <REVENUECAT_WEBHOOK_SECRET> header'ı beklenir.

Credit Packages Konfigürasyonu

Veritabanı Şeması

Credit Package şeması (credit-package.schema.ts):

Store'a Göre Store Identifier Formatları

Kredi Paketi Oluşturma Akışı

1. RevenueCat Dashboard'da veya store'da ürünü oluşturun
2. revenuecatProductId değerini RevenueCat'ten alın (genellikle prod ile başlar)
3. API üzerinden paketi oluşturun:

curl -X POST https://your-domain.com/api/credit-packages \
  -H "Authorization: Bearer <ADMIN_JWT>" \
  -H "Content-Type: multipart/form-data" \
  -F "creditAmount=100" \
  -F "storeIdentifier=credit100" \
  -F "storeType=apple" \
  -F "revenuecatProductId=prode52bdad1dc"

Environment Variables Referansı

Zorunlu Değişkenler

# RevenueCat temel konfigürasyon
REVENUECAT_SECRET_KEY=sk_xxxxxxxxxxxxx
REVENUECAT_PROJECT_ID=proj_xxxxxxxxxxxxx

# Store App ID'leri (Test ve Apple zorunlu)
REVENUECAT_APP_ID_TEST=appae0e1f5439
REVENUECAT_APP_ID_APPLE=appd24d573b8b

Opsiyonel Değişkenler

# Webhook doğrulama (Production'da önerilir)
REVENUECAT_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

# API base URL (varsayılan: https://api.revenuecat.com/v2)
REVENUECAT_BASE_URL=https://api.revenuecat.com/v2

# Opsiyonel store App ID'leri
REVENUECAT_APP_ID_GOOGLE=app_xxxxxxxxxxxxx
REVENUECAT_APP_ID_WEB=app_xxxxxxxxxxxxx

Validation Kuralları (Joi)

Store Type Eşleştirmesi

RevenueCat webhook'unda gelen store değeri ile sistemin storeType değeri eşleştirilir:

App ID Seçimi

Kredi paketi oluşturulurken storeType'a göre otomatik App ID seçilir:

Product ID vs Store Identifier

Sistemde iki farklı product tanımlayıcı kullanılır:

Önemli: RevenueCat webhook'unun product_id alanı genellikle storeIdentifier değerine karşılık gelir. Credit package lookup bu değer üzerinden yapılır.

Konfigürasyon Kontrol Listesi

Başlamadan Önce

• RevenueCat hesabı oluşturuldu
• Proje oluşturuldu ve Project ID alındı
• API Key (V2) oluşturuldu ve Secret Key kaydedildi

Environment Ayarları

• REVENUECAT_SECRET_KEY .env'e eklendi
• REVENUECAT_PROJECT_ID .env'e eklendi
• REVENUECAT_APP_ID_TEST .env'e eklendi
• REVENUECAT_APP_ID_APPLE .env'e eklendi
• REVENUECAT_WEBHOOK_SECRET .env'e eklendi (Production için)

RevenueCat Dashboard

• Test Store app eklendi
• Apple app eklendi (App Store Connect ile bağlandı)
• Webhook oluşturuldu ve URL ayarlandı
• Webhook secret kopyalandı

Store Ürünleri

• App Store Connect'te consumable ürünler oluşturuldu
• RevenueCat'te ürünler eşleştirildi veya Virtual Currency olarak tanımlandı
• Kredi paketleri Allmine API ile oluşturuldu

Test

• GET /api/credit-packages paketleri listeliyor
• Webhook test event'i başarılı yanıt veriyor
• Gerçek test satın alma kredileri ekliyor

Sorun Giderme

"RevenueCat configuration is missing"

Sebep: Config validation başarısız (eksik veya hatalı env değişkenleri).

Çözüm:

• .env dosyasını kontrol edin
• Zorunlu değişkenlerin hepsinin tanımlı olduğundan emin olun
• Uygulamayı yeniden başlatın

"Webhook secret not configured" / "Invalid RevenueCat webhook"

Sebep: REVENUECAT_WEBHOOK_SECRET tanımlı değil veya RevenueCat Dashboard'daki secret ile eşleşmiyor.

Çözüm:

• REVENUECAT_WEBHOOK_SECRET env'e ekleyin
• Webhook endpoint'i Authorization: Bearer <secret> bekler; RevenueCat bu header'ı otomatik ekler
• Dashboard'dan webhook secret'ı tekrar kopyalayın

"Credit package not found for product ID"

Sebep: Webhook'taki product_id, veritabanındaki herhangi bir storeIdentifier ile eşleşmiyor.

Çözüm:

• RevenueCat'ten gelen product_id değerini loglayın
• Credit package oluştururken storeIdentifier olarak bu değeri kullanın
• Aynı storeType ile eşleşen paket olup olmadığını kontrol edin

"Google Play Store app ID is not configured"

Sebep: storeType: google ile paket oluşturuluyor ancak REVENUECAT_APP_ID_GOOGLE tanımlı değil.

Çözüm:

• .env'e REVENUECAT_APP_ID_GOOGLE=app_xxx ekleyin
• Veya sadece Apple/Test store kullanıyorsanız, Google paketi oluşturmayın

Transaction duplicate / idempotency

Sistem event.id ile duplicate event'leri filtreler. Aynı event tekrar gelirse işlenmez.

Ek Kaynaklar

• Entegrasyon Rehberi - API endpoint'leri, kullanım örnekleri
• RevenueCat API v2
• RevenueCat Webhooks