Goru Ads Flutter SDK — Entegrasyon Rehberi
Mobil uygulamalarınıza yüksek eCPM oranlarıyla kolayca reklam entegre edin ve kazanç sağlamaya başlayın.
1. Kurulum
Projenize Goru Ads SDK'sını eklemek için pubspec.yaml dosyanızın bağımlılıklar (dependencies) kısmına şu satırı ekleyin:
dependencies:
flutter:
sdk: flutter
goru_ads_sdk:
git:
url: https://github.com/merterenai/goru-ads.git
path: Sdk/flutter/goru_ads_sdk
SDK şu an kapalı betadadır (pub.dev'de yayınlanmaz); özel repoya erişim gerekir. Ardından flutter pub get çalıştırın.
2. Başlatma (Initialization)
SDK'yı uygulama açılışında bir kez başlatın. Yayıncı panelinden aldığınız appId ve appSecret ile (appSecret'ı kaynak koda gömmeyin, --dart-define ile verin):
Future<void> main() async {
WidgetsFlutterBinding.ensureInitialized();
await GoruAds.initialize(
baseUrl: 'https://goruads.com/api',
appId: 'APP_ID_NIZ',
appSecret: const String.fromEnvironment('GORU_APP_SECRET'),
onSdkStatus: (status, config) {
// update_required / blocked / disabled → kullanıcıyı yönlendirin
},
);
runApp(const MyApp());
}
// Sonrasında her yerde:
final client = GoruAds.client;
initialize uzaktan ayarları ve sürüm durumunu okur, kayıtlı rıza kararını yükler; 30 saniyede tamamlanmazsa uygulamanızı bekletmez. Başlatmadan önce reklam istemek GoruNotInitializedException fırlatır.
3. Reklam Formatları
Goru Ads, uygulamanızın farklı alanlarına uyum sağlayacak esnek reklam biçimleri sunar.
Banner Reklam
Ekranın alt veya üst kısımlarında sabit kalan standart reklam alanlarıdır.
final ad = await client.requestAd(
placementId: 'banner-home',
format: AdFormat.banner,
);
// Widget ağacında:
GoruBannerAd(ad: ad, client: client)
// Ya da kendi kendini yenileyen (Server'ın bildirdiği sürede), uyarlanabilir banner:
GoruBannerView(client: client, placementId: 'banner-home', adaptiveWidth: 320)
Geçiş Reklamı (Interstitial)
Ekran geçişlerinde (örneğin seviye atlandığında veya menüler arası) tam ekran gösterilen reklamlardır.
final interstitial = await GoruInterstitialAd.load(
client: client,
placementId: 'interstitial-level',
);
// Uygun anda göster:
await interstitial.show(context);
Ödüllü Reklam (Rewarded)
Kullanıcıların reklamı sonuna kadar izleyerek uygulama içi ödül kazandığı format.
final rewarded = await GoruRewardedAd.load(
client: client,
placementId: 'rewarded-life',
);
rewarded.setServerSideVerificationOptions(userId: 'oyuncu-42', customData: 'seviye-3');
final earned = await rewarded.show(context); // yalnızca sonuna kadar izlenirse true
if (earned) grantReward(rewarded.rewardAmount, rewarded.rewardType);
Yerel Reklam (Native)
Uygulamanızın arayüz tasarımına tamamen uyum sağlayan özelleştirilebilir reklamlar.
final native = await GoruNativeAd.load(
client: client,
placementId: 'native-list',
);
// Widget ağacında (zorunlu "Reklam" etiketi dahildir):
GoruNativeAdView(ad: native, client: client)
Uygulama Açılış (App Open)
Uygulama ön plana geldiğinde gösterilen tam ekran reklam. Yönetici yaşam döngüsünü izler, sonraki reklamı önceden yükler; kullanıcı reklama tıklayıp uygulamadan çıkarsa dönüşte tekrar göstermez.
final manager = GoruAppOpenAdManager(
client: GoruAds.client,
placementId: 'app-open',
navigatorKey: navigatorKey, // MaterialApp.navigatorKey
)..start();
Ödüllü Geçiş (Rewarded Interstitial)
Doğal bir geçişte (ör. seviye sonu) açılır. Önce ödülü bildiren, geri sayımlı ve vazgeçilebilir bir tanıtım ekranı gösterilir; kullanıcı vazgeçerse reklam hiç gösterilmez.
final ad = await GoruRewardedInterstitialAd.load(
client: client,
placementId: 'rewarded-interstitial',
);
final earned = await ad.show(context);
4. AB Rıza (GDPR)
AB/EEA kullanıcıları için rıza formu hazırdır. Mesaj metni sunucudan gelir (hukuki içerik ve sürüm yönetimi orada); SDK formu çizer, kararı kaydeder ve rıza bayraklarını tüm isteklere otomatik ekler. "Reddet" ve "Kabul" aynı ağırlıktadır, kutular varsayılan kapalıdır.
// Açılışta: gerekliyse (AB'de, karar yoksa/mesaj değiştiyse) formu gösterir
await GoruAds.showConsentFormIfRequired(context);
// Ayarlar ekranında KALICI bir yerden: seçimi değiştir / rızayı geri çek
await GoruAds.showPrivacyOptions(context);
Karar yerelde saklanır, sunucuya kaydedilir ve yeni cihazda geri yüklenir. Hukuki onay tamamlanana kadar sunucu mesajı yayınlamaz; bu durumda form gösterilmez.
5. Ödül Doğrulama
Ödüllü reklam bitince SDK ödülü sunucuda doğrulatır; sunucu yayıncının adresine imzalı bir geri çağırma gönderir (ECDSA P-256; Google SSV ile aynı kalıp). Panelden rewardCallbackUrl tanımlayın ve imzayı GET /api/reward-keys genel anahtarlarıyla doğrulayın.
// Varsayılan: ödül hemen verilir, doğrulama arka planda yapılır
final earned = await rewarded.show(context);
// Ödül oyun ekonomisini etkiliyorsa: sunucu doğrulayana kadar bekle
final earned = await rewarded.show(context, awaitVerification: true);
Verilecek miktar için sunucunun değeri esastır (await rewarded.verifyReward()).
6. Hata Modeli ve Reklam Yok
Tüm hatalar GoruAdsException'dır (code, statusCode, retryAfter); metne değil koda bakın.
GoruNoFillException— uygun reklam yok.retryAfterdolmadan SDK aynı yer için ağa gitmez; uygulamanız reklamsız devam etmelidir.GoruSdkDisabledException— hizmet geçici kapalı (kill switch).GoruSdkVersionException— SDK sürümü desteklenmiyor, güncelleyin.- Önbellekteki reklamın süresi dolunca (
isReady == false) yeniden yükleyin.
7. Test Modu ve Ayarlar
Debug derlemede istekler test trafiği sayılır: gelir, istatistik ve harcamaya girmez, reklamda "Test Reklamı" etiketi görünür. Release derlemede test modu her zaman kapalıdır.
GoruAds.requestConfiguration = const GoruRequestConfiguration(
ageRestrictedTreatment: AgeRestrictedTreatment.child, // çocuk modu
maxAdContentRating: GoruContentRating.g,
);
await GoruAds.initialize(...); // ayarı başlatmadan ÖNCE atayın
Çocuk modunda kullanıcı ve cihaz verisi hiç gönderilmez, yalnızca G dereceli reklam gelir (envanter az olabilir).
App ID'nizi Nereden Alırsınız?
Yayıncı panelinize giriş yaptıktan sonra Uygulamalarım sayfasına giderek size özel oluşturulan appId ve appSecret değerlerini kopyalayabilirsiniz. appSecret gizlidir; yalnızca derleme zamanında (--dart-define) verin.
Sık Sorulan Sorular
Ödeme koşulları (eşik, dönem, yöntem) kapalı beta süresince yayıncıyla ayrıca netleştirilir; panelde henüz otomatik ödeme yoktur.
Debug derlemede istekler otomatik test trafiği sayılır (gelir üretmez). Sunucu olmadan arayüzü denemek için SDK'daki buildMockBannerAd() gibi sahte reklam üreticilerini kullanabilirsiniz.