本指南適用於需要建立中介服務轉接程式的廣告聯播網。發布商請參閱發布商中介服務操作說明。
中介服務轉接程式是廣告聯播網與 Google 行動廣告中介服務之間的通訊層。轉接程式會放送來自您廣告聯播網的廣告,並將相關廣告事件轉送至 AdMob。轉接程式會負責實作 GADMAdNetworkAdapter
通訊協定,確保提供所需功能。
必要條件
- Xcode 15.3 以上版本
- 部署目標 8.0 以上版本
- Google Mobile Ads iOS SDK 下載的「中介服務轉接程式」資料夾內的額外標頭
您的廣告聯播網必須與 Google 建立合作關係,才能建立中介服務轉接程式。
廣告聯播網範例
本指南說明如何建立「廣告聯播網範例」的轉接程式。「廣告聯播網範例 SDK」包含類別,代表大部分廣告聯播網提供的類別:
@interface SampleBanner : UILabel
@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleBannerAdDelegate> delegate;
- (void)fetchAd:(SampleAdRequest *)request;
@end
typedef NS_ENUM(NSInteger, SampleErrorCode) {
SampleErrorCodeBadRequest = 0,
SampleErrorCodeUnknown = 1,
SampleErrorCodeNetworkError = 2,
SampleErrorCodeNoInventory = 3,
};
@interface SampleAdRequest : NSObject
@property(nonatomic, assign) BOOL testMode;
@property(nonatomic, copy) NSArray *keywords;
@end
@interface SampleInterstitial : NSObject
@property(nonatomic, copy) NSString *adUnit;
@property(nonatomic, weak) id<SampleInterstitialAdDelegate> delegate;
@property(nonatomic, assign, getter=isInterstitialLoaded) BOOL interstitialLoaded;
- (void)fetchAd:(SampleAdRequest *)request;
- (void)show;
@end
@protocol SampleBannerAdDelegate
- (void)bannerDidLoad:(SampleBanner *)banner;
- (void)banner:(SampleBanner *)banner didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)bannerWillLeaveApplication:(SampleBanner *)banner;
@end
@protocol SampleInterstitialAdDelegate<NSObject>
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial;
- (void)interstitial:(SampleInterstitial *)interstitial
didFailToLoadAdWithError:(SampleErrorCode)error;
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial;
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial;
@end
如要進一步瞭解這些類別,請參閱 SDK 實作的完整範例。
連接器
中介服務轉接程式會使用導入 GADMAdNetworkConnector
通訊協定的物件與 Google Mobile Ads SDK 互動。我們接著會把這個物件稱為連接器連接器會公開廣告請求的必要資訊,並提供廣告事件和使用者互動回呼中介服務的方法。連接器會在初始化時提供給中介服務轉接程式。設定轉接程式,將連接器儲存在執行個體變數中:
- (id)initWithGADMAdNetworkConnector:(id<GADMAdNetworkConnector>)c {
if ((self = [super init])) {
_connector = c;
}
return self;
}
伺服器參數
您的廣告聯播網可能需要 ID 來識別發布商。舉例來說,「廣告聯播網範例」需要一個廣告單元。這些必要伺服器參數會透過 credentials
方法提供給轉接程式,進而傳回 ID 和對應值的 NSDictionary
。以下這行程式碼會從連接器擷取廣告聯播網範例名為 ad_unit
的伺服器參數:
self.interstitialAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];
中介服務聯播網設定
廣告聯播網必須向 AdMob 告知聯播網所需的伺服器參數。這樣 AdMob 就能在前端設定您的聯播網。
在前端啟用聯播網進行中介服務時,AdMob 會要求您輸入將轉接程式例項化所需的值。以下螢幕截圖顯示 Millennial Media 需要應用程式刊登位置 ID (APID),且 InMobi 需要應用程式 ID。
如要進一步瞭解如何設定中介服務廣告聯播網,請參閱這篇文章。
發出中介服務廣告請求
橫幅要求
如果是中介服務橫幅廣告請求,系統會在轉接程式執行個體化後立即呼叫 getBannerWithSize
方法。這個方法不會傳回任何內容。指示轉接器開始透過聯播網開始非同步擷取廣告。讓轉接程式監聽 SDK 回呼。如果您的 SDK 不支援指定的廣告大小,或不支援橫幅廣告,請在連接器上叫用 adapter:didFailAd:
方法。
導入「廣告聯播網範例」的 getBannerWithSize
看起來會像這樣:
- (void)getBannerWithSize:(GADAdSize)adSize {
//The adapter should fail immediately if the adSize is not supported
if (!GADAdSizeEqualToSize(adSize, GADAdSizeBanner) &&
!GADAdSizeEqualToSize(adSize, GADAdSizeMediumRectangle) &&
!GADAdSizeEqualToSize(adSize, GADAdSizeFullBanner) &&
!GADAdSizeEqualToSize(adSize, GADAdSizeLeaderboard)) {
NSString *errorDesc =
[NSString stringWithFormat:@"Invalid ad type %@, not going to get ad.",
NSStringFromGADAdSize(adSize)];
NSDictionary *errorInfo = [NSDictionary
dictionaryWithObjectsAndKeys:errorDesc, NSLocalizedDescriptionKey, nil];
NSError *error = [NSError errorWithDomain:GADErrorDomain
code:GADErrorMediationInvalidAdSize
userInfo:errorInfo];
[self.connector adapter:self didFailAd:error];
return;
}
self.bannerAd = [[SampleBanner alloc]
initWithFrame:CGRectMake(0, 0, adSize.size.width, adSize.size.height)];
self.bannerAd.delegate = self;
self.bannerAd.adUnit = [[self.connector credentials] objectForKey:@"ad_unit"];
// Setup request parameters.
SampleAdRequest *request = [[SampleAdRequest alloc] init];
request.testMode = self.connector.testMode;
request.keywords = self.connector.userKeywords;
[self.bannerAd fetchAd:request];
NSLog(@"Requesting banner from Sample Ad Network");
}
其他指定目標參數
連接器包含一些常見的指定目標資訊,可做為指定廣告目標的參考:
userKeywords
testMode
childDirectedTreatment
中介服務額外功能
中介服務額外功能可讓廣告聯播網支援連接器提供的額外要求參數未涵蓋的額外指定目標參數或輸入項目。您可以透過實作 GADAdNetworkExtras
通訊協定的類別提供這項功能。以下為 SampleAdNetworkExtras
類別的範例:
@interface SampleAdNetworkExtras : NSObject <GADAdNetworkExtras>
/// Should ad volume audio be muted.
@property(nonatomic, assign) BOOL muteAudio;
@end
發布商必須在發出廣告請求時傳遞 GADAdNetworkExtras
子類別的例項。您可以透過連接器存取這個 GADAdNetworkExtras
子類別的例項。以下說明如何在為聯播網建立廣告請求時,運用中介服務額外功能:
SampleAdRequest *request = [[SampleAdRequest alloc] init];
SampleAdNetworkExtras *myAdNetworkExtras = [self.connector networkExtras];
request.muteAudio = myAdNetworkExtras.muteAudio;
[self.bannerAd fetchAd:request];
為確保您的 GADAdNetworkExtras
子類別可以透過連接器存取,請實作 networkExtrasClass
並傳回 GADAdNetworkExtras
子類別:
+ (Class<GADAdNetworkExtras>)networkExtrasClass {
return [SampleAdNetworkExtras class];
}
如果轉接程式沒有使用中介服務額外功能,networkExtrasClass
方法會傳回 Nil
。
通知中介服務
讓轉接程式為聯播網導入廣告事件監聽器,並透過連接器轉送相關廣告事件回呼。下表說明每個委派方法的呼叫時機:
方法 | 聯絡時機 |
---|---|
adapter:didReceiveAdView: |
橫幅廣告請求成功。 |
adapter:didFailAd: |
橫幅廣告請求失敗。 |
adapterDidGetAdClick: |
橫幅已點擊。 |
adapterWillPresentFullScreenModal: |
橫幅會顯示應用程式內的重疊元素。 |
adapterWillDismissFullScreenModal: |
關閉應用程式內重疊元素。 |
adapterDidDismissFullScreenModal: |
應用程式內重疊廣告已關閉。 |
adapterWillLeaveApplication: |
應用程式會顯示在背景或終止,因為使用者點選會啟動其他應用程式的廣告。 |
以下範例導入「廣告聯播網範例」中的 SampleBannerAdDelegate
介面,以轉送錯誤和狀態訊息:
- (void)bannerDidLoad:(SampleBanner *)banner {
[self.connector adapter:self didReceiveAdView:banner];
}
- (void)banner:(SampleBanner *)banner didFailWithError:(SampleErrorCode)error {
[self.connector adapter:self
didFailAd:[NSError errorWithDomain:@"Ad request failed"
code:error
userInfo:nil]];
}
- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
[self.connector adapterDidGetAdClick:self];
[self.connector adapterWillLeaveApplication:self];
}
啟動應用程式內重疊與外部應用程式
使用者點按橫幅廣告時,廣告可能會開啟全螢幕重疊廣告或外部應用程式 (例如 Safari 或應用程式商店)。這兩種情況叫用的連接器回呼不同。
如果橫幅廣告點擊會開啟全螢幕重疊,請在顯示疊加層時呼叫 adapterWillPresentFullScreenModal:
。疊加層關閉時,請同時呼叫 adapterWillDismissFullScreenModal:
和 adapterDidDismissFullScreenModal:
。
如果點選橫幅廣告 (或點選全螢幕重疊元素) 導致使用者離開應用程式,請叫用 adapterWillLeaveApplication:
回呼。
您現在已有可用的橫幅廣告中介服務轉接程式。您可以前往 GitHub 查看 SampleAdapter
的完整實作。
導入插頁式廣告轉接程式
插頁式廣告的轉接程式導入方式與橫幅廣告類似。轉換介面執行個體化後,系統就會立即呼叫 getInterstitial
方法。這個方法不會傳回任何內容。轉接程式應透過聯播網啟動非同步廣告擷取作業。請將轉接程式設為 SDK 的委派項目,以便監聽回呼。如果 SDK 不支援插頁式廣告,請叫用連接器的 adapter:didFailAd:
方法,如下所示:
- (void)getInterstitial {
self.interstitialAd = [[SampleInterstitial alloc] init];
self.interstitialAd.delegate = self;
self.interstitialAd.adUnit =
[[self.connector credentials] objectForKey:@"ad_unit"];
SampleAdRequest *request = [[SampleAdRequest alloc] init];
// Setup request parameters.
request.testMode = self.connector.testMode;
request.keywords = self.connector.userKeywords;
[self.interstitialAd fetchAd:request];
NSLog(@"Requesting interstitial from Sample Ad Network");
}
和 MediationBannerAdapter
一樣,您可以從連接器接收發布商識別資訊和廣告指定資訊。
通知中介服務
讓轉接程式為聯播網導入廣告委派,並透過連接器轉送相關廣告事件回呼。下表說明各個委派方法的呼叫時機:
方法 | 聯絡時機 |
---|---|
adapterDidReceiveInterstitial: |
插頁式廣告請求成功。 |
adapter:didFailInterstitial: |
插頁式廣告請求失敗。 |
adapterDidGetAdClick: |
插頁式廣告被點擊。 |
adapterWillPresentInterstitial: |
系統會顯示插頁式廣告。 |
adapterWillDismissInterstitial: |
插頁式廣告即將關閉。 |
adapterDidDismissInterstitial: |
插頁式廣告已關閉。 |
adapterWillLeaveApplication: |
應用程式會在背景或終止,因為使用者點選會啟動其他應用程式的廣告。 |
以下範例導入「廣告聯播網範例」的 SampleInterstitialAdDelegate
介面,以轉送錯誤和狀態訊息:
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
[self.connector adapterDidReceiveInterstitial:self];
}
- (void)interstitial:(SampleInterstitial *)interstitial
didFailWithError:(SampleErrorCode)error {
[self.connector adapter:self
didFailInterstitial:[NSError errorWithDomain:@"Ad request failed"
code:error
userInfo:nil]];
}
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
[self.connector adapterWillPresentInterstitial:self];
}
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
[self.connector adapterWillDismissInterstitial:self];
}
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
[self.connector adapterDidDismissInterstitial:self];
}
顯示插頁式廣告
轉接程式呼叫 adapterDidReceiveInterstitial
後,請等到呼叫 presentInterstitialFromRootViewController
後再顯示插頁。應用程式開發人員會決定顯示插頁式廣告的時機,可能是收到插頁式廣告後幾分鐘。
以下是「廣告聯播網範例」的 presentInterstitialFromRootViewController:
導入方法:
- (void)presentInterstitialFromRootViewController:
(UIViewController *)rootViewController {
if ([self.interstitialAd isLoaded]) {
[self.interstitialAd show];
}
}
您的中介服務轉接程式已準備就緒,可以處理插頁式廣告。您可以在 GitHub 找到 SampleAdapter
的完整實作,供您參考。
常見問題
- 我應該將轉接程式納入 SDK 程式庫或其他程式庫嗎?
- 建議將轉接程式納入 SDK 程式庫,讓開發人員只要參照一個程式庫即可納入您的聯播網。
- 轉接程式只支援橫幅廣告,該怎麼辦?
如果您的轉接程式僅支援橫幅廣告,請將錯誤事件轉送至插頁式廣告請求的中介服務:
- (void)getInterstitial { NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" }; NSError *error = [NSError errorWithDomain:GADErrorDomain code:GADErrorInvalidRequest userInfo:errorInfo]; [self.connector adapter:self didFailInterstitial:error]; return; }
- 轉接程式只支援插頁式廣告,該怎麼辦?
如果您的轉接程式僅支援插頁式廣告,請將錯誤事件轉送至橫幅廣告請求的中介服務:
- (void)getBannerWithSize:(GADAdSize)adSize { NSDictionary *errorInfo = @{ NSLocalizedDescriptionKey : @"Some error" }; NSError *error = [NSError errorWithDomain:GADErrorDomain code:GADErrorInvalidRequest userInfo:errorInfo]; [self.connector adapter:self didFailAd:error]; return; }