261 lines
7.9 KiB
Markdown
261 lines
7.9 KiB
Markdown
# 📦 ShiroginSDK Popup Service (v1.0.0)
|
||
|
||
**Event-Driven Popup Management • ServiceLocator Integration • DOTween Animations**
|
||
|
||
Bu doküman, **ShiroginSDK v1.0.0** sürümünde güncellenen `PopupService` sistemini açıklar.
|
||
Yeni mimari, `ServiceBase` tabanlı olup tüm servisler `ShiroginServiceRegistry` tarafından başlatılır.
|
||
`PopupService`, `EventService` üzerinden tetiklenen event’lere yanıt verir ve `PopupRepository`’deki prefab’lar aracılığıyla popup’ları yönetir.
|
||
|
||
---
|
||
|
||
## 🚀 1. Genel Bakış
|
||
|
||
`PopupService`, oyun boyunca kullanıcıya gösterilen tüm popup’ları (ödül, hata, bağlantı hatası, satın alma, reklam vb.) kontrol eder.
|
||
|
||
**Özellikler:**
|
||
* ✅ `ServiceBase` tabanlı bağımsız servis yapısı
|
||
* ✅ `ServiceLocator` ile erişim
|
||
* ✅ `EventService` üzerinden otomatik popup tetikleme
|
||
* ✅ `DOTween` tabanlı açılış / kapanış animasyonları
|
||
* ✅ `PopupRepository` üzerinden prefab yönetimi
|
||
* ✅ Otomatik queue sistemi (popup’lar sırayla gösterilir)
|
||
|
||
---
|
||
|
||
## 🧩 2. Mimari Bileşenler
|
||
|
||
| Bileşen | Tip | Açıklama |
|
||
|---------------------|------------------|-----------|
|
||
| **PopupService** | `ServiceBase` | Tüm popup kuyruğunu ve animasyonları yönetir. |
|
||
| **PopupRepository** | `ScriptableObject` | Popup prefab referanslarını tutar. |
|
||
| **UIPopupBase** | `MonoBehaviour` | Her popup prefab’ının temel sınıfıdır. |
|
||
|
||
---
|
||
|
||
## 🧠 3. Servis Mimarisi
|
||
|
||
### 🔹 Başlatma
|
||
|
||
Tüm servisler otomatik olarak `ShiroginServiceRegistry.InitializeAll()` çağrısı ile başlatılır.
|
||
|
||
```csharp
|
||
ShiroginServiceRegistry.InitializeAll();
|
||
````
|
||
|
||
Bu çağrı `EventService`, `PopupService`, `AnalyticsService`, `IAPService` gibi tüm servisleri oluşturur ve `ServiceLocator`’a kaydeder.
|
||
|
||
---
|
||
|
||
### 🔹 Erişim
|
||
|
||
`PopupService` artık singleton değil.
|
||
Servise erişim `ServiceLocator` üzerinden yapılır:
|
||
|
||
```csharp
|
||
var popupService = ServiceLocator.Get<IPopupService>();
|
||
popupService.Show(PopupType.RewardClaimed, eventData);
|
||
```
|
||
|
||
---
|
||
|
||
## 🪄 4. Popup Gösterme Yöntemleri
|
||
|
||
### 🔸 1️⃣ EventService Üzerinden Otomatik Gösterim
|
||
|
||
`PopupService`, `IEventService`’e abonedir ve belirli `ShiroginEvents` event’lerine yanıt verir.
|
||
Aşağıdaki event’ler otomatik olarak popup tetikler:
|
||
|
||
| Event Tipi | Gösterilen PopupType |
|
||
| ---------------------------- | --------------------------------- |
|
||
| `RewardClaimedEvent` | `PopupType.RewardClaimed` |
|
||
| `PurchaseCompletedEvent` | `PopupType.PurchaseSuccess` |
|
||
| `PurchaseFailedEvent` | `PopupType.PurchaseFailed` |
|
||
| `NoConnectionEvent` | `PopupType.NoConnection` |
|
||
| `RewardedAdUnavailableEvent` | `PopupType.RewardedAdUnavailable` |
|
||
|
||
**Örnek:**
|
||
|
||
```csharp
|
||
var eventService = ServiceLocator.Get<IEventService>();
|
||
eventService.Invoke(new ShiroginEvents.RewardClaimedEvent("daily_bonus", "Daily Reward", 100, "Gold"));
|
||
```
|
||
|
||
`PopupService`, bu event’i dinler ve otomatik olarak `RewardClaimed` popup’ını sıraya alır.
|
||
|
||
---
|
||
|
||
### 🔸 2️⃣ Kod Üzerinden Manuel Gösterim
|
||
|
||
```csharp
|
||
var popupService = ServiceLocator.Get<IPopupService>();
|
||
popupService.Show(PopupType.NoConnection, new ShiroginEvents.NoConnectionEvent());
|
||
```
|
||
|
||
Bu yöntemle event olmadan da popup manuel olarak sıraya eklenebilir.
|
||
|
||
---
|
||
|
||
## 🧩 5. Yeni Popup Eklemek
|
||
|
||
### 1️⃣ Yeni Prefab Oluştur
|
||
|
||
1. `Assets/ShiroginSDK/UI/Popups/` klasörüne git.
|
||
2. Yeni prefab oluştur (örnek: `UIPopup_LevelUp`).
|
||
3. `UIPopupBase`’den türeyen script ekle:
|
||
|
||
```csharp
|
||
using UnityEngine;
|
||
using ShiroginSDK.Runtime.UI.Scripts.UI.Base;
|
||
|
||
public class UIPopup_LevelUp : PopupBase
|
||
{
|
||
[SerializeField] private TMPro.TextMeshProUGUI levelText;
|
||
|
||
public override void Initialize(object data)
|
||
{
|
||
if (data is ShiroginEvents.PlayerLevelUpEvent e)
|
||
levelText.text = $"LEVEL {e.NewLevel}";
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2️⃣ PopupType Enum’una Ekle
|
||
|
||
```csharp
|
||
public enum PopupType
|
||
{
|
||
RewardClaimed,
|
||
PurchaseSuccess,
|
||
LevelUp,
|
||
NoConnection,
|
||
PurchaseFailed,
|
||
RewardedAdUnavailable
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3️⃣ PopupRepository’ye Ekle
|
||
|
||
1. `Assets/Resources/PopupRepository.asset` dosyasını aç.
|
||
2. Yeni satır ekle:
|
||
|
||
* **PopupType:** `LevelUp`
|
||
* **Prefab:** `UIPopup_LevelUp`
|
||
|
||
---
|
||
|
||
### 4️⃣ Test Et
|
||
|
||
```csharp
|
||
var popupService = ServiceLocator.Get<IPopupService>();
|
||
popupService.Show(PopupType.LevelUp, new ShiroginEvents.PlayerLevelUpEvent(9, 10, 500));
|
||
```
|
||
|
||
veya event tabanlı:
|
||
|
||
```csharp
|
||
ServiceLocator.Get<IEventService>().Invoke(new ShiroginEvents.PlayerLevelUpEvent(9, 10, 500));
|
||
```
|
||
|
||
---
|
||
|
||
## 🎬 6. Animasyon ve Kuyruk Sistemi
|
||
|
||
Popup’lar sırayla gösterilir.
|
||
Yeni bir popup çağrıldığında, mevcut popup kapanana kadar bekler.
|
||
Kapanış tamamlandığında sıradaki popup açılır.
|
||
|
||
**Akış:**
|
||
|
||
```
|
||
RewardClaimed → PurchaseSuccess → NoConnection
|
||
```
|
||
|
||
**DOTween Animasyonları:**
|
||
|
||
* Fade in/out (arka plan karartması)
|
||
* Scale up (açılış animasyonu)
|
||
* Scale down (kapanış animasyonu)
|
||
|
||
---
|
||
|
||
## ⚙️ 7. Kullanılabilir API
|
||
|
||
| Fonksiyon / Özellik | Açıklama |
|
||
| ------------------------------------- | ------------------------------------------- |
|
||
| `Show(PopupType, object)` | Popup gösterir. |
|
||
| `Enqueue(PopupType, object)` | Popup’ı sıraya ekler. |
|
||
| `SetCanvas(Canvas canvas)` | Root canvas atanır. |
|
||
| `SetRepository(PopupRepository repo)` | Repository dinamik olarak değiştirilebilir. |
|
||
|
||
---
|
||
---
|
||
|
||
## 🧩 8. Servis Entegrasyonu
|
||
|
||
PopupService, şu servislerle entegre çalışır:
|
||
|
||
| Servis | Amaç |
|
||
| ------------------- | ----------------------------------- |
|
||
| `IEventService` | Popup tetikleme event’lerini dinler |
|
||
| `IDataService` | Gerekirse popup bazlı veri erişimi |
|
||
| `IAnalyticsService` | Popup açılma logları (isteğe bağlı) |
|
||
|
||
Bu sistem, SDK genelinde **event-driven** iletişim modeline bağlıdır.
|
||
Hiçbir servis diğerine doğrudan referans vermez — tüm bağlantılar `ServiceLocator` üzerinden yapılır.
|
||
|
||
---
|
||
|
||
## 🧱 10. Örnek Dosya Yapısı
|
||
|
||
```
|
||
Assets/
|
||
└── ShiroginSDK/
|
||
├── Runtime/
|
||
│ ├── Core/
|
||
│ │ └── SDKInitializer.cs
|
||
│ ├── Services/
|
||
│ │ ├── Base/
|
||
│ │ └── Implementations/
|
||
│ │ └── PopupService.cs
|
||
│ └── UI/
|
||
│ ├── PopupBase.cs
|
||
│ └── UIPopup_LevelUp.cs
|
||
└── Resources/
|
||
└── PopupRepository.asset
|
||
```
|
||
|
||
---
|
||
|
||
## 🧾 11. Özet
|
||
|
||
| İşlem | Nasıl Yapılır | Örnek |
|
||
| --------------- | ------------------------------------- | ----------------------------------------------------------------- |
|
||
| Popup göster | `ServiceLocator.Get<IPopupService>()` | `popupService.Show(PopupType.RewardClaimed, data)` |
|
||
| Event tetikle | `ServiceLocator.Get<IEventService>()` | `eventService.Invoke(new ShiroginEvents.RewardClaimedEvent(...))` |
|
||
| Yeni popup ekle | Prefab + Enum + Repository | `UIPopup_LevelUp` |
|
||
| Kuyruk sistemi | Otomatik | Popup kapanmadan yeni popup gösterilmez |
|
||
|
||
---
|
||
|
||
## ✅ 12. Örnek Akış
|
||
|
||
1. Oyuncu günlük ödül alır
|
||
2. `RewardClaimedEvent` tetiklenir
|
||
3. `IEventService` popup servisine sinyal gönderir
|
||
4. `PopupService` `RewardClaimed` popup’ını sıraya ekler
|
||
5. DOTween ile popup açılır
|
||
6. Kapanış sonrası sıradaki popup gösterilir
|
||
|
||
---
|
||
|
||
**Prepared by:** Emir Han MAMAK
|
||
|
||
**Version:** 1.1.0 (2025.12)
|
||
|
||
**Module:** ShiroginSDK.Runtime.Services.Implementations.UI.PopupService
|
||
|
||
---
|