Sự kiện tùy chỉnh

Hướng dẫn này dành cho những nhà xuất bản đang tìm cách thêm tùy chọn hỗ trợ cho các sự kiện tùy chỉnh của quảng cáo xen kẽ và biểu ngữ trong hoạt động dàn xếp AdMob.

Sự kiện tùy chỉnh cho phép bạn đặt bất kỳ chế độ xem nào mà bạn muốn vào không gian quảng cáo. Thông qua các sự kiện tùy chỉnh, bạn cũng có thể kiếm tiền từ ứng dụng bằng các mạng quảng cáo không được hoạt động dàn xếp hỗ trợ trực tiếp. Một sự kiện tùy chỉnh sẽ được triển khai thông qua giao thức GADCustomEventBanner hoặc GADCustomEventInterstitial.

Điều kiện tiên quyết

Trước khi có thể tích hợp các sự kiện tùy chỉnh cho một định dạng quảng cáo, bạn cần tích hợp định dạng quảng cáo đó vào ứng dụng của mình. Dưới đây là các hướng dẫn có liên quan:

Mạng quảng cáo mẫu

Hướng dẫn này minh họa cách phân phát quảng cáo xen kẽ và biểu ngữ từ Mạng quảng cáo mẫu bằng cách dùng các lớp sự kiện tùy chỉnh SampleCustomEventBannerSampleCustomEventInterstital. SDK của Mạng quảng cáo mẫu là một SDK mô phỏng được phát triển để minh họa cách triển khai trong thực tế của một sự kiện tùy chỉnh. SDK này chứa các lớp là đại diện của các lớp được hầu hết mạng quảng cáo cung cấp. Hãy xem cách triển khai SDK mẫu hoàn chỉnh để biết thêm thông tin về các lớp này.

Trong ví dụ sau, trước tiên bạn cần tạo một sự kiện tùy chỉnh của biểu ngữ trong hoạt động dàn xếp AdMob. Việc này yêu cầu bạn phải xác định một sự kiện tùy chỉnh trỏ đến lớp cụ thể đó trong ứng dụng thông qua giao diện người dùng AdMob, sau đó triển khai một sự kiện tùy chỉnh của biểu ngữ để trả về một chế độ xem.

Xác định một sự kiện tùy chỉnh

Sự kiện tùy chỉnh phải được xác định trong giao diện người dùng AdMob . Bài viết Tạo một sự kiện tùy chỉnh sẽ hướng dẫn cách di chuyển trong giao diện người dùng này.

Dưới đây là ảnh chụp màn hình hiển thị một số tùy chọn cài đặt của sự kiện tùy chỉnh mẫu:

Bảng dưới đây chứa các thông tin hướng dẫn về cách điền các thông số này.

Tên nhóm

Nhập tên nhóm hoàn toàn đủ điều kiện cho lớp sẽ triển khai sự kiện tùy chỉnh.

Nếu lớp được triển khai trong Swift, bạn cần thêm vào trước tên lớp tên của ứng dụng/mô-đun khung (ví dụ: appName.className).

Bắt buộc phải có tên mục tiêu nếu bạn có nhiều mục tiêu trong dự án hoặc nếu tên dự án khác với tên mục tiêu. Với tên mục tiêu, tên nhóm sẽ giống như sau: appName_targetName.className. Ngoài ra, hãy nhớ thay thế mọi ký tự không phải chữ-số như dấu gạch ngang với dấu gạch dưới.

Để biết thêm chi tiết, hãy xem ví dụ này.

Nhãn Nhập một tên duy nhất cho sự kiện này.
Thông số Nếu bạn muốn chuyển một đối số tới sự kiện tùy chỉnh, hãy nhập chuỗi phù hợp.

Yêu cầu biểu ngữ

Đối với yêu cầu biểu ngữ của sự kiện tùy chỉnh, phương thức requestBannerAd:parameter:label:request: sẽ được gọi ngay lập tức sau khi lớp sự kiện tùy chỉnh được thực thế hóa. Phương thức này không trả về bất cứ giá trị nào. Giả định là sự kiện tùy chỉnh sẽ bắt đầu tìm nạp quảng cáo không đồng bộ trên mạng. Sự kiện tùy chỉnh của bạn sẽ hoạt động như một đại biểu (delegate) cho SDK để lắng nghe lệnh gọi ngược.

Nếu SDK của bạn không hỗ trợ kích thước quảng cáo đã cho hoặc không hỗ trợ quảng cáo biểu ngữ, hãy gọi phương thức customEventBanner:didFailAd: của đại biểu sự kiện tùy chỉnh. Các thông số serverParameterserverLabel tương ứng với các trường nhãn và thông số đã xác định khi tạo một sự kiện tùy chỉnh trong giao diện người dùng AdMob.

Dưới đây là hoạt động triển khai mẫu của requestBannerAd:parameter:label:request: bằng cách dùng Mạng quảng cáo mẫu:

Swift

func requestBannerAd(adSize: GADAdSize, parameter serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  // Create a banner view with the appropriate size.
  bannerAd = SampleBanner(frame: CGRectMake(
      0, 0, adSize.size.width, adSize.size.height))
  bannerAd.delegate = self
  bannerAd.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  bannerAd.fetchAd(adRequest)
}

Objective-C

- (void)requestBannerAd:(GADAdSize)adSize
              parameter:(NSString *)serverParameter
                  label:(NSString *)serverLabel
                request:(GADCustomEventRequest *)request {
  // Create the bannerView with the appropriate size.
  self.bannerAd =
      [[SampleBanner alloc] initWithFrame:CGRectMake(0,
                                                     0,
                                                     adSize.size.width,
                                                     adSize.size.height)];

  self.bannerAd.delegate = self;
  self.bannerAd.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.bannerAd fetchAd:adRequest];
}

Gửi các phần bổ sung mạng quảng cáo cho các yêu cầu sự kiện tùy chỉnh

Để gửi phần phụ mạng quảng cáo kèm theo yêu cầu đến sự kiện tùy chỉnh để xử lý, bạn sẽ sử dụng hàm GADRequest registerAdNetworkExtras:. Bạn phải tạo một bản sao của GADCustomEventExtras (phù hợp với giao thức GADAdNetworkExtras ) để điền thuộc tính GADCustomEventRequest.additionalParameters. Để chuyển vào các phần phụ, hãy gọi GADCustomEventExtras setExtras:forLabel:, chuyển vào các phần phụ dưới dạng một từ điển và nhãn của sự kiện tùy chỉnh mà bạn đã xác định trong giao diện người dùng AdMob.

Dưới đây là một đoạn mã cho thấy cách chuyển một thông số SampleExtra cho nhãn SampleCustomEvent đã được xác định trước đó:

Swift

let request = GADRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective-C

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

Nếu bạn không đăng ký một bản sao của GADCustomEventExtras cho một yêu cầu sự kiện tùy chỉnh, thuộc tính additionalParameters của GADCustomEventRequest sẽ là nil.

Thông báo cho hoạt động dàn xếp AdMob

Triển khai trình xử lý quảng cáo cho mạng của bạn và gọi các lệnh gọi ngược liên quan trên đại biểu của thông số tùy chỉnh để gửi thông báo về lại cho hoạt động dàn xếp. Ví dụ sau triển khai giao diện SampleBannerAdDelegate của Mạng quảng cáo mẫu để gửi các thông báo sau:

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when banner ad has loaded.
func bannerDidLoad(banner: SampleBanner!) {
  delegate.customEventBanner(self, didReceiveAd: banner)
}

// Sent when banner has failed to load.
func banner(banner: SampleBanner!, didFailToLoadAdWithErrorCode error: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventBanner.customEventErrorDomain,
      code: error.rawValue, userInfo: nil)
  delegate.customEventBanner(self, didFailAd: nsError)
}

// Sent when a banner is clicked and an external application is launched
func bannerWillLeaveApplication(banner: SampleBanner!) {
  delegate.customEventBannerWasClicked(self)
  delegate.customEventBannerWillLeaveApplication(self)
}

Objective-C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when banner ad has loaded.
- (void)bannerDidLoad:(SampleBanner *)banner {
  [self.delegate customEventBanner:self didReceiveAd:banner];
}

// Sent when banner has failed to load.
- (void)banner:(SampleBanner *)banner
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventBanner:self didFailAd:error];
}

// Sent when a banner is clicked and an external application is launched.
- (void)bannerWillLeaveApplication:(SampleBanner *)banner {
  [self.delegate customEventBannerWasClicked:self];
  [self.delegate customEventBannerWillLeaveApplication:self];
}

Xem cách triển khai mẫu của một biển ngữ sự kiện tùy chỉnh để biết thêm thông tin.

Sự kiện tùy chỉnh quảng cáo xen kẽ

Cách triển khai một sự kiện tùy chỉnh của quảng cáo xem kẻ cũng tương tư như cách triển khai sự kiện tùy chỉnh của biểu ngữ. Điểm khác biệt chính là lớp sự kiện tùy chỉnh của quảng cáo xen kẻ mà bạn tạo sẽ triển khai giao thức GADCustomEventInterstitial thay vì giao thức GADCustomEventBanner.

Xác định một sự kiện tùy chỉnh

Sự kiện tùy chỉnh phải được xác định trong giao diện người dùng AdMob . Bài viết Tạo một sự kiện tùy chỉnh sẽ hướng dẫn cách di chuyển trong giao diện người dùng này.

Dưới đây là ảnh chụp màn hình hiển thị một số tùy chọn cài đặt của sự kiện tùy chỉnh mẫu:

Bảng dưới đây chứa các thông tin hướng dẫn về cách điền các thông số này.

Tên nhóm

Nhập tên nhóm hoàn toàn đủ điều kiện cho lớp sẽ triển khai sự kiện tùy chỉnh.

Nếu lớp được triển khai trong Swift, bạn cần thêm vào trước tên lớp tên của ứng dụng/mô-đun khung (ví dụ: appName.className).

Bắt buộc phải có tên mục tiêu nếu bạn có nhiều mục tiêu trong dự án hoặc nếu tên dự án khác với tên mục tiêu. Với tên mục tiêu, tên nhóm sẽ giống như sau: appName_targetName.className. Ngoài ra, hãy nhớ thay thế mọi ký tự không phải chữ-số như dấu gạch ngang với dấu gạch dưới.

Để biết thêm chi tiết, hãy xem ví dụ này.

Nhãn Nhập một tên duy nhất cho sự kiện này.
Thông số Nếu bạn muốn chuyển một đối số tới sự kiện tùy chỉnh, hãy nhập chuỗi phù hợp.

Yêu cầu quảng cáo xen kẽ

Đối với yêu cầu quảng cáo xen kẽ của sự kiện tùy chỉnh, phương thức requestInterstitialAdWithParameter:label:request: sẽ được gọi ngay lập tức sau khi lớp sự kiện tùy chỉnh được thực thế hóa. Phương thức này không trả về bất cứ giá trị nào. Giả định là sự kiện tùy chỉnh sẽ bắt đầu tìm nạp quảng cáo không đồng bộ trên mạng.

Sự kiện tùy chỉnh của bạn sẽ hoạt động như một đại biểu (delegate) cho SDK để lắng nghe lệnh gọi ngược. Các thông số serverParameterserverLabel tương ứng với các trường nhãn và thông số đã xác định khi tạo một sự kiện tùy chỉnh trong giao diện người dùng AdMob.

Dưới đây là hoạt động triển khai mẫu của requestInterstitialAdWithParameter:label:request: bằng cách dùng Mạng quảng cáo mẫu:

Swift

func requestInterstitialAdWithParameter(serverParameter: String!,
    label serverLabel: String!, request: GADCustomEventRequest!) {
  interstitial = SampleInterstitial()
  interstitial.delegate = self
  interstitial.adUnit = serverParameter
  let adRequest = SampleAdRequest()
  adRequest.testMode = request.isTesting
  adRequest.keywords = request.userKeywords
  interstitial.fetchAd(adRequest)
}

Objective-C

- (void)requestInterstitialAdWithParameter:(NSString *)serverParameter
                                     label:(NSString *)serverLabel
                                   request:(GADCustomEventRequest *)request {
  self.interstitial = [[SampleInterstitial alloc] init];
  self.interstitial.delegate = self;
  self.interstitial.adUnit = serverParameter;
  SampleAdRequest *adRequest = [[SampleAdRequest alloc] init];
  adRequest.testMode = request.isTesting;
  adRequest.keywords = request.userKeywords;
  [self.interstitial fetchAd:adRequest];
}

Giao thức của sự kiện tùy chỉnh GADCustomEventInterstitial yêu cầu bạn triển khai phương thức presentFromRootViewController:. Hoạt động dàn xếp gọi phương thức này khi bạn yêu cầu SDK quảng cáo trên thiết bị di động hiển thị quảng cáo xen kẽ như sau:

Swift

func presentFromRootViewController(rootViewController: UIViewController!) {
  if interstitial.interstitialLoaded {
    interstitial.show()
  }
}

Objective-C

- (void)presentFromRootViewController:(UIViewController *)rootViewController {
  if ([self.interstitial isInterstitialLoaded]) {
    [self.interstitial show];
  }
}

Gửi các phần bổ sung mạng quảng cáo cho các yêu cầu sự kiện tùy chỉnh

Để gửi phần phụ mạng quảng cáo kèm theo yêu cầu đến sự kiện tùy chỉnh để xử lý, bạn sẽ sử dụng hàm GADRequest registerAdNetworkExtras:. Bạn phải tạo một bản sao của GADCustomEventExtras (phù hợp với giao thức GADAdNetworkExtras ) để điền thuộc tính GADCustomEventRequest.additionalParameters. Để chuyển vào các phần phụ, hãy gọi GADCustomEventExtras setExtras:forLabel:, để chuyển vào các phần phụ dưới dạng một từ điển và nhãn của sự kiện tùy chỉnh mà bạn đã xác định trong giao diện người dùng AdMob.

Dưới đây là một đoạn mã cho thấy cách chuyển một thông số SampleExtra cho nhãn SampleCustomEvent đã được xác định trước đó:

Swift

let request = GADRequest()
let extras = GADCustomEventExtras()
extras.setExtras(["SampleExtra": true], forLabel: "SampleCustomEvent")
request.register(extras)

Objective-C

GADRequest *request = [GADRequest request];
GADCustomEventExtras *extras = [[GADCustomEventExtras alloc] init];
[extras setExtras:@{@"SampleExtra": @(YES)} forLabel:@"SampleCustomEvent"];
[request registerAdNetworkExtras:extras];

Nếu bạn không đăng ký một bản sao của GADCustomEventExtras cho một yêu cầu sự kiện tùy chỉnh, thuộc tính additionalParameters của GADCustomEventRequest sẽ là nil.

Thông báo cho hoạt động dàn xếp AdMob

Triển khai trình xử lý quảng cáo cho mạng của bạn và gọi các lệnh gọi ngược liên quan trên đại biểu của thông số tùy chỉnh để gửi thông báo về lại cho hoạt động dàn xếp. Ví dụ sau triển khai giao diện SampleInterstitialAdDelegate của Mạng quảng cáo mẫu để gửi các thông báo sau:

Swift

/// Type property for Sample Ad Network custom event error domain.
static let customEventErrorDomain = "com.google.CustomEvent"

// Sent when an interstitial ad has loaded.
func interstitialDidLoad(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidReceiveAd(self)
}

// Sent when interstitial ad has failed to load.
func interstitial(interstitial: SampleInterstitial!,
    didFailToLoadAdWithErrorCode errorCode: SampleErrorCode) {
  let nsError = NSError(domain: SampleCustomEventInterstitial.customEventErrorDomain,
      code: errorCode.rawValue, userInfo: nil)
  delegate.customEventInterstitial(self, didFailAd: nsError)
}

// Sent when an interstitial is about to be shown.
func interstitialWillPresentScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillPresent(self)
}

// Sent when an interstitial is about to be dismissed.
func interstitialWillDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWillDismiss(self)
}

// Sent when an interstitial has been dismissed.
func interstitialDidDismissScreen(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialDidDismiss(self)
}

// Sent when an interstitial is clicked and an external application is launched.
func interstitialWillLeaveApplication(interstitial: SampleInterstitial!) {
  delegate.customEventInterstitialWasClicked(self)
  delegate.customEventInterstitialWillLeaveApplication(self)
}

Objective-C

/// Constant for Sample Ad Network custom event error domain.
static NSString *const customEventErrorDomain = @"com.google.CustomEvent";

// Sent when an interstitial ad has loaded.
- (void)interstitialDidLoad:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidReceiveAd:self];
}

// Sent when an interstitial ad has failed to load.
- (void)interstitial:(SampleInterstitial *)interstitial
    didFailToLoadAdWithErrorCode:(SampleErrorCode)errorCode {
  NSError *error = [NSError errorWithDomain:customEventErrorDomain
                                       code:errorCode
                                   userInfo:nil];
  [self.delegate customEventInterstitial:self didFailAd:error];
}

// Sent when an interstitial is about to be shown.
- (void)interstitialWillPresentScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillPresent:self];
}

// Sent when an interstitial is about to be dismissed.
- (void)interstitialWillDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWillDismiss:self];
}

// Sent when an interstitial has been dismissed.
- (void)interstitialDidDismissScreen:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialDidDismiss:self];
}

// Sent when an interstitial is clicked and an external application is launched.
- (void)interstitialWillLeaveApplication:(SampleInterstitial *)interstitial {
  [self.delegate customEventInterstitialWasClicked:self];
  [self.delegate customEventInterstitialWillLeaveApplication:self];
}

Việc gửi thông báo về lại cho hoạt động dàn xếp cho phép sự kiện tùy chỉnh tiếp tục quy trình dàn xếp.

Xem bài viết cách triển khai mẫu của một sự kiện tùy chỉnh của quảng cáo xen kẽ để biết thêm thông tin.