الموافقة والتحكم — iOS
لا ترمي أي دالة من دوال Ad80 استثناءً ولا تنهار بسبب ما تمرّره إليها. والدوال start وregister وunregister معلَّمة بـ @MainActor:
استدعِها من الخيط الرئيسي. أما بقية الدوال فيمكنك استدعاؤها من أي خيط بأمان.
التهيئة والبدء
Section titled “التهيئة والبدء”لا يبدأ SDK وحده على iOS. استدعِ Ad80.start(integrations:) مرة واحدة من
application(_:didFinishLaunchingWithOptions:) قبل ظهور أول عرض إعلان.
يقرأ الاستدعاء الأول ملف Info.plist (المفاتيح AD80PublisherKey وAD80Endpoint وAD80Enabled)، ويبني SDK ويبدأ
المراقبة. ولا يرسل أي طلب شبكة قبل الموافقة. أما الاستدعاءات اللاحقة فلا تفعل سوى تثبيت الربط الذي لم يُثبَّت بعد،
ولا تغيّر شيئاً غيره: تبقى الإعدادات والموافقة والتفعيل وأماكن العرض كما هي.
import UIKitimport GoogleMobileAdsimport Ad80import Ad80GoogleMobileAds
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { Ad80.start(integrations: [Ad80GoogleMobileAds.integration]) MobileAds.shared.start(completionHandler: nil) return true}لا يحتوي تطبيق SwiftUI على app delegate افتراضياً، فأضف واحداً:
@main struct MyApp: App { @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate var body: some Scene { WindowGroup { ContentView() } }}استدعِ Ad80.start(integrations:) داخل application(_:didFinishLaunchingWithOptions:) في هذا الـ delegate كما في
تبويب UIKit. وعروض البانر المغلّفة في UIViewRepresentable يجدها SDK مثل أي BannerView آخر ما دامت داخل
نافذة. اجعل العرض الذي يعيده الـ representable هو عرض Google نفسه، ولا تضع داخله شيئاً من عندك.
@import Ad80GoogleMobileAds;@import Ad80;
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { [AD80GoogleMobileAds startAD80]; return YES;}إن استدعيت Ad80.start() بلا ربط، يبدأ SDK دون اكتشاف إعلانات Google Mobile Ads: يُبلغ عن adMobUnavailable
مرة واحدة، ولا يراقب إلا العروض التي تسجّلها أنت بنفسك.
الموافقة
Section titled “الموافقة”لا يلتقط SDK شيئاً ولا يرسل شيئاً قبل منح الموافقة. وSDK لا يحفظ الموافقة، لذا استدعِ
Ad80.setConsent(...) في كل مرة يبدأ فيها التطبيق، فور معرفتك باختيار المستخدم. مثلاً بعد انتهاء مسار الموافقة
عندك (كمنصة Google لرسائل المستخدمين UMP).
import Ad80
// After your consent flow, on every start:Ad80.setConsent(consentInformation.canRequestAds)[AD80 setConsent:YES];consentInformation هنا هو كائن ConsentInformation من UMP عندك. استخدم ما يحدّد الموافقة في تطبيقك أياً كان.
سحب الموافقة (Ad80.setConsent(false)) يوقف الالتقاط والطلبات فوراً، ويحذف كل ما ينتظر في الطابور على
الجهاز (ويُبلغ SDK عن disabled(CONSENT_REVOKED)). ولن يُرسَل لاحقاً أي شيء كان في الطابور قبل سحب الموافقة.
مفتاح الإيقاف المحلي
Section titled “مفتاح الإيقاف المحلي”| الطريقة | الأثر |
|---|---|
Ad80.setEnabled(false) | يوقف SDK في هذه العملية: يتوقف الالتقاط والرفع ويُحذف الطابور (disabled(LOCAL)). وتعيد Ad80.setEnabled(true) تشغيله. لا تُحفظ هذه الحالة بين العمليات. |
المفتاح AD80Enabled بقيمة false (Boolean) في Info.plist | يصبح SDK خاملاً في العملية كلها: لا يلتقط شيئاً ويُبلغ عن disabled(INFO_PLIST). استخدمه مثلاً في إعداد بناء (build configuration) يجب ألّا يُبلغ عن الإعلانات. وغيابه يعني أن SDK مفعّل. |
Ad80.setEnabled(false) // for example from a remote flag or a settings screen[AD80 setEnabled:NO];الإعدادات عن بُعد (مفتاح الإيقاف لدى AD80)
Section titled “الإعدادات عن بُعد (مفتاح الإيقاف لدى AD80)”يقرأ SDK إعداداته عن بُعد. بعد منح الموافقة، وما دام SDK مفعّلاً، يجلب إعداداته من AD80 (عبر GET /v1/config على العنوان نفسه)، ثم
يجلبها من جديد بعد كل ttlSeconds:
{ "enabled": true, "captureEnabled": true, "uploadEnabled": true, "ttlSeconds": 3600, "fullScreenCaptureEnabled": true }| الحقل | الأثر |
|---|---|
enabled | القيمة false توقف الالتقاط والرفع وتحذف الطابور. ويبقى هذا سارياً، حتى بعد إعادة التشغيل، إلى أن تأتي إعدادات لاحقة تعيد تفعيل SDK. وفي هذه الأثناء يواصل SDK فحص الإعدادات. |
captureEnabled | القيمة false توقف التقاط إعلانات جديدة. |
uploadEnabled | القيمة false توقف الرفع. |
fullScreenCaptureEnabled | القيمة false تتخطى الإعلانات بملء الشاشة (والنتيجة SKIPPED_FULLSCREEN_DISABLED)، وتُسقط ملاحظات الإعلانات بملء الشاشة التي في الطابور ولم تُسلَّم بعد. ولا يهمّ إلا الإعلانات التي يتتبّعها تطبيقك بـ Ad80.trackFullScreenAd. ويلزم لالتقاطها أن تكون enabled وcaptureEnabled وهذا الحقل كلها true. ويستطيع المالك والمشرفون تغييره لكل تطبيق من لوحة المتابعة، في التطبيقات وإعداد SDK. |
ttlSeconds | مدة صلاحية الإعدادات. يُبقيها SDK بين 300 و86400 ثانية. |
إن فشل الجلب، يواصل SDK العمل بآخر إعدادات وصلته (أو بالقيم الافتراضية أعلاه إن لم تصله إعدادات قط، إلا أن الالتقاط بملء الشاشة يبقى مغلقاً حتى تصله إعدادات)، ويحاول مجدداً بعد 15 دقيقة. ومع كل فشل جديد ينتظر مدة أطول، حتى يوم كامل.
المفتاح المحفوظ لكل تطبيق يكون مفعّلاً افتراضياً، لكن SDK نفسه يبدأ والقيمة fullScreenCaptureEnabled مغلقة، ويعدّ الحقل المفقود
أو الخاطئ مغلقاً. لذلك لا يبدأ الالتقاط بملء الشاشة إلا بعد أن يجلب SDK إعدادات تفتحه.
على الخطة المجانية تأتي الإعدادات بالقيمة enabled: false، فيبقى SDK المدمج في التطبيق خاملاً حتى تنتقل
المؤسسة إلى خطة تشمل الربط مع SDK. ويستطيع AD80 أيضاً إيقاف تطبيق مؤقتاً بطلب منك؛ راسلنا على
contact@ad80.dev.