213 lines
7.4 KiB
Markdown
213 lines
7.4 KiB
Markdown
# 🛒 ShiroginSDK IAP System (v1.0.0)
|
||
|
||
**Unity In-App Purchase Entegrasyonu + Oyun İçi Ekonomi + Ödül + Event-Driven Mimari**
|
||
|
||
Bu doküman, **ShiroginSDK v1.0.0** sürümüyle güncellenen IAP (In-App Purchase) altyapısını açıklar.
|
||
Yeni sistem, **ShiroginServiceRegistry** üzerinden başlatılan **modüler servis yapısına** sahiptir.
|
||
Tüm satın alma işlemleri, **event tabanlı** olarak SDK genelindeki diğer servislerle otomatik senkronize edilir.
|
||
|
||
---
|
||
|
||
## 🚀 1. Genel Bakış
|
||
|
||
ShiroginSDK IAP sistemi:
|
||
|
||
* ✅ `ServiceBase` tabanlı, modüler ve bağımsız servis yapısı
|
||
* ✅ `EventService` ile tam event forwarding desteği
|
||
* ✅ Unity IAP, oyun içi ekonomi, sandık, bundle ve reklamla ödül sistemleri
|
||
* ✅ Otomatik `AnalyticsService` & `PopupService` entegrasyonu
|
||
* ✅ Tek konfigürasyon noktası: `SDKConfig.storeRepository`
|
||
|
||
---
|
||
|
||
## 🧩 2. Servis Mimarisi
|
||
|
||
### 🔹 IAPService (Yeni Sistem)
|
||
|
||
`IAPService`, artık `ServiceBase`’ten türetilen bir servis olarak `ShiroginServiceRegistry` tarafından otomatik olarak başlatılır.
|
||
Kendi bağımlılıklarını `ServiceLocator` aracılığıyla çözer.
|
||
|
||
**Başlatma:**
|
||
|
||
```csharp
|
||
ShiroginServiceRegistry.InitializeAll();
|
||
````
|
||
|
||
Bu çağrı, IAPService dahil tüm servisleri (`EventService`, `DataService`, `FirebaseService`, `AnalyticsService`) otomatik olarak oluşturur.
|
||
|
||
**IAPService Görevleri:**
|
||
|
||
* Unity IAP sistemini başlatır (`UnityPurchasing.Initialize()`).
|
||
* Satın alma işlemlerini yönetir.
|
||
* Başarılı işlemlerde ödül verir (`StoreItem.GiveReward()`).
|
||
* EventService üzerinden satın alma event’lerini yayınlar.
|
||
|
||
**Kilit Eventler:**
|
||
|
||
```csharp
|
||
_eventService.Invoke(new ShiroginEvents.PurchaseCompletedEvent(product, 1)); // Analytics
|
||
_eventService.Invoke(new ShiroginEvents.Shop_UIStoreItem_Rewarded(item.GetRewards())); // Popup
|
||
```
|
||
|
||
---
|
||
|
||
### 🔹 DataService Entegrasyonu (v1.0.0 Güncel)
|
||
|
||
Yeni sistemde `DataService`, `ServiceBase`’ten türetilen bağımsız bir servistir.
|
||
`ServiceLocator` aracılığıyla erişilir ve oyun boyunca tüm veri nesnelerini (`RuntimeData`, `EconomyData`, `StoreData`, `InventoryData` vb.) yönetir.
|
||
|
||
```csharp
|
||
var dataService = ServiceLocator.Get<IDataService>();
|
||
|
||
var storeData = dataService.Get<StoreData>();
|
||
storeData.MarkPurchased(productId, 1, item.category);
|
||
|
||
var runtime = dataService.Get<RuntimeData>();
|
||
runtime.UpdatePlaySessionCount();
|
||
```
|
||
|
||
Artık **`DataService.Get<T>()`** gibi statik çağrılar yerine, `ServiceLocator` üzerinden interface tabanlı erişim kullanılmalıdır.
|
||
Bu sayede her servis, kendi yaşam döngüsünde `OnInitialize()` içinde `IDataService`’i çözer ve paylaşılan state’i korur.
|
||
|
||
> 🔹 `IDataService` → `Get<T>()`, `Save<T>()`, `Delete<T>()` gibi tip güvenli fonksiyonlar sağlar.
|
||
> 🔹 `DataService` runtime'da `DontDestroyOnLoad` olarak yaşar.
|
||
> 🔹 Oyun verileri JSON tabanlı olarak `Application.persistentDataPath || PlayerPrefs` altında tutulur.
|
||
|
||
---
|
||
|
||
### 🔹 EventService Entegrasyonu
|
||
|
||
Her önemli işlem event tabanlı çalışır.
|
||
IAPService, `EventService` üzerinden ShiroginEvents yayınlayarak SDK içindeki diğer sistemlere sinyal gönderir.
|
||
|
||
Örneğin:
|
||
|
||
* `PurchaseCompletedEvent` → `AnalyticsService` tarafından loglanır
|
||
* `Shop_UIStoreItem_Rewarded` → `PopupService` tarafından UI bildirimi gösterilir
|
||
|
||
---
|
||
|
||
## 💳 3. IAPService API Özeti
|
||
|
||
| Metod | Açıklama |
|
||
| ------------------------------------ | ------------------------------------------ |
|
||
| `Buy(StoreItem item)` | Belirtilen ürünü satın alır. |
|
||
| `Buy(string productId)` | Product ID ile satın alma başlatır. |
|
||
| `RestorePurchases()` | Kalıcı ürünleri geri yükler (iOS/Android). |
|
||
| `GetLocalizedPriceString(productId)` | Cihazın mağaza diline uygun fiyat döner. |
|
||
|
||
---
|
||
|
||
## 🧠 4. Akış Diyagramı
|
||
|
||
```
|
||
[UIStoreItem_Consumable.OnPurchaseButton]
|
||
↓
|
||
[IAPService.Buy()]
|
||
↓
|
||
Unity IAP Purchase Flow
|
||
↓
|
||
[IAPService.ProcessPurchase()]
|
||
↓
|
||
[StoreItem.GiveReward()]
|
||
↓
|
||
[EventService.Invoke(ShiroginEvents.PurchaseCompletedEvent)]
|
||
↓
|
||
[AnalyticsService + PopupService]
|
||
```
|
||
|
||
Tüm veri ve event akışı tek hattan ilerler.
|
||
Bu sayede loglama, ödül ve UI işlemleri birbiriyle senkronize yürür.
|
||
|
||
---
|
||
|
||
## 🧰 5. Editor & Test Özellikleri
|
||
|
||
* **FakeStore Modu:**
|
||
Unity Editor içinde `StandardPurchasingModule` otomatik olarak FakeStore’u açar.
|
||
Test sırasında gerçek ödeme yapılmaz.
|
||
|
||
```csharp
|
||
module.useFakeStoreAlways = true;
|
||
module.useFakeStoreUIMode = FakeStoreUIMode.StandardUser;
|
||
```
|
||
|
||
* **Loglama:**
|
||
Başarılı ve başarısız tüm işlemler konsola `[IAPService]` etiketiyle yazılır.
|
||
|
||
---
|
||
|
||
## 🪙 6. Ekonomi & Ödül Yönetimi
|
||
|
||
IAP sistemi, **EconomyData** ve **RewardDefinition** ile entegredir:
|
||
|
||
* Satın alma sonrası ödül → `StoreItem.GiveReward()`
|
||
* Sandık → `StoreItem.GiveRandomReward()`
|
||
* Kaldırılan reklamlar → `RewardType.RemoveAds`
|
||
* Currency tabanlı satın alma → `EconomyData.SpendCurrency()`
|
||
|
||
---
|
||
|
||
## 🔔 7. Event Referansları
|
||
|
||
| Event | Açıklama |
|
||
| ---------------------------- | ---------------------------------------- |
|
||
| `PurchaseCompletedEvent` | Satın alma başarıyla tamamlandı. |
|
||
| `PurchaseFailedEvent` | Satın alma başarısız oldu. |
|
||
| `RewardGivenEvent` | Ödül verildi. |
|
||
| `Shop_UIStoreItem_Rewarded` | Mağaza ödül popup’ı tetiklendi. |
|
||
| `NoConnectionEvent` | İnternet bağlantısı yok. |
|
||
| `RewardedAdUnavailableEvent` | Reklam izlenemedi (AdsService kaynaklı). |
|
||
|
||
---
|
||
|
||
## 🧩 8. Yeni Mimarideki Geliştirmeler
|
||
|
||
| Alan | Yenilik |
|
||
| ---------------------------- | ------------------------------------------------------------ |
|
||
| **Lifecycle** | Tüm servisler `ServiceBase` üstünden yönetilir. |
|
||
| **Bağımlılıklar** | `ServiceLocator` ile otomatik çözülür. |
|
||
| **Otomatik EventForwarding** | `EventService` ile doğrudan bağlı. |
|
||
| **Firebase Entegrasyonu** | Satın alma logları otomatik olarak `FirebaseService`’e akar. |
|
||
| **Gelişmiş Restore Logic** | Android ve iOS için unified restore desteği. |
|
||
| **UI Bağımsızlık** | Tüm item’ler `UIStoreItemBase` tabanlı. |
|
||
|
||
---
|
||
|
||
## 🧠 9. Örnek Kod: Mağaza Butonu
|
||
|
||
```csharp
|
||
public void OnGemPackButton()
|
||
{
|
||
var store = ServiceLocator.Get<IIAPService>();
|
||
var item = store.StoreRepository.GetByProductId("com.shirogin.gem_pack_1");
|
||
store.Buy(item);
|
||
}
|
||
```
|
||
|
||
Satın alma tamamlandığında:
|
||
|
||
* Oyuncuya ödül verilir.
|
||
* `AnalyticsService` log gönderir.
|
||
* `PopupService` başarı mesajı gösterir.
|
||
|
||
---
|
||
|
||
## 🧾 10. Özet
|
||
|
||
ShiroginSDK IAP System v1.0.0,
|
||
tamamen **event-driven**, **service-oriented** ve **UI-modüler** bir yapıdadır.
|
||
Tüm işlemler `ServiceRegistry` tarafından kontrol edilir,
|
||
ve sonuçlar SDK genelinde otomatik olarak paylaşılır.
|
||
|
||
> 🔗 Tam uyumlu servisler:
|
||
> **EventService**, **AnalyticsService**, **PopupService**, **EconomyData**, **RemoteConfigService**
|
||
|
||
---
|
||
|
||
**Prepared by:** Emir Han MAMAK
|
||
|
||
**Version:** 1.1.0 (2025.12)
|
||
|
||
**Module:** ShiroginSDK.Runtime.Services.Implementations.IAP
|
||
|