Bắt đầu

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

• Xcode 13 trở lên

Hướng dẫn này mô tả cách gọi SDK PAL để nhận số chỉ dùng một lần và màn hình các sự kiện phát. Để làm theo hướng dẫn hoàn chỉnh này, hãy tải Ứng dụng mẫu PAL tvOS.

Thêm SDK PAL vào dự án của bạn

Cài đặt SDK PAL bằng Trình quản lý gói Swift

SDK Thư viện quyền truy cập có lập trình hỗ trợ Gói Swift Manager kể từ phiên bản 2.5.3. Làm theo các bước bên dưới để nhập gói Swift.

1. Trong Xcode, hãy cài đặt Gói IMA SDK Swift bằng cách chuyển đến Tệp > Thêm gói....

2. Khi lời nhắc xuất hiện, hãy tìm GitHub Package SDK Swift kho lưu trữ:

   https://github.com/googleads/swift-package-manager-google-programmatic-access-library-tvos
   

3. Chọn phiên bản Gói Swift SDK PAL mà bạn muốn sử dụng. Đối với các dự án mới, bạn nên sử dụng phiên bản Up to Next Major Version (Lên phiên bản lớn tiếp theo).

Sau khi bạn hoàn tất, Xcode sẽ giải quyết các phần phụ thuộc của gói và tải chúng xuống trong nền. Để biết thêm chi tiết về cách thêm gói phần phụ thuộc, hãy xem Bài viết của Apple.

Tải xuống và cài đặt SDK PAL theo cách thủ công

Nếu không muốn sử dụng Trình quản lý gói Swift, bạn có thể tải SDK PAL xuống và thêm nó vào dự án của bạn theo cách thủ công.

1. Tải xuống và giải nén SDK PAL cho iOS
2. Làm theo Hướng dẫn cho nhà phát triển của Apple để tích hợp khung này vào dự án của bạn.

Tạo một số chỉ dùng một lần

"Nonce" là một chuỗi được mã hoá do PAL tạo ra bằng cách sử dụng PALNonceLoader. SDK PAL đòi hỏi mỗi yêu cầu luồng mới phải được đi kèm bởi một số chỉ dùng một lần mới tạo. Tuy nhiên, số chỉ dùng một lần có thể được sử dụng lại cho nhiều quảng cáo các yêu cầu trong cùng một luồng.

Tất cả các đoạn mã dưới đây là nội dung sửa đổi đối với ViewController.m trong Ứng dụng mẫu PAL tvOS.

Để yêu cầu một số chỉ dùng một lần, hãy bắt đầu bằng cách nhập thư viện PAL:

@import ProgrammaticAccessLibrary;

Lưu ý: Bạn chỉ nên tạo một phiên bản của thuộc tính PALNonceLoader cho mỗi phiên người dùng trong ứng dụng, trừ phi ứng dụng của bạn có nhiều trang hoặc cấu trúc tương đương. Điều này giúp trang trở thành yếu tố tương quan, hoặc Tham số &correlator, không thay đổi trong toàn bộ thời gian của một trang hoặc của người dùng phiên hoạt động của ứng dụng.

Bạn vẫn có quyền kiểm soát đối với bộ tương quan luồng, hoặc &scor. Giá trị này phải đặt lại một lần cho mỗi luồng mới. Tất cả các yêu cầu quảng cáo của cùng một luồng sẽ chia sẻ cùng PALNonceLoader và giá trị tương quan luồng cho giới hạn tần suất và để các tính năng loại trừ cạnh tranh hoạt động hiệu quả.

Tiếp theo, hãy tạo một thực thể của PALNonceLoader và thêm mã giả lập cho hai thực thể đó phương thức uỷ quyền:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The view in which a video would play.
// In this sample, it is mocked for simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end
...
- (void) viewDidLoad {
  [super viewDidLoad];
  // The default value for 'allowStorage' and
  // 'directedForChildOrUnknownAge' is 'NO', but should be updated once the
  // appropriate consent has been gathered. Publishers should either
  // integrate with a CMP or use a different method to handle storage consent.
  PALSettings *settings = [[PALSettings alloc] init];
  settings.allowStorage = YES;
  settings.directedForChildOrUnknownAge = NO;

  self.nonceLoader = [[PALNonceLoader alloc] initWithSettings:settings];
  self.nonceLoader.delegate = self;
}

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
}

Sau đó, hãy khởi tạo yêu cầu số chỉ dùng một lần, điền các thuộc tính và sử dụng yêu cầu đó để khởi chạy trình quản lý số chỉ dùng một lần:

@interface ViewController () <PALNonceLoaderDelegate>
// The nonce loader to use for nonce requests.
@property(nonatomic) PALNonceLoader *nonceLoader;
// The nonce manager result from the last successful nonce request.
@property(nonatomic) PALNonceManager *nonceManager;
// The view in which a video would play. In this sample, it is mocked for
// simplification.
@property(nonatomic, weak) IBOutlet UIView *videoView;
@end

...

- (void)viewDidLoad {
  ...
  self.nonceLoader.delegate = self;
  [self requestNonceManager];
}

...

#pragma mark - UI Callback methods

/**
 * Requests a new nonce manager with a request containing arbitrary test values
 * like a (sane) user might supply. Displays the nonce or error on success. This
 * should be called once per stream.
 *
 * The PALNonceRequest parameters set here are example parameters.
 * You should set your parameters based on your own app characteristics.
 */
- (void)requestNonceManager {
  PALNonceRequest *request = [[PALNonceRequest alloc] init];
  request.continuousPlayback = PALFlagOff;
  request.descriptionURL = [NSURL URLWithString:@"https://example.com/desc?key=val"];
  request.iconsSupported = YES;
  request.playerType = @"AwesomePlayer";
  request.playerVersion = @"4.2.1";
  request.PPID = @"123987456";
  request.sessionID = @"Sample SID";
  // Sample API framework integer. See reference docs for more details.
  NSInteger SampleAPIFramework = 501;
  request.supportedApiFrameworks = [NSMutableSet setWithArray:@[ SampleAPIFramework ]];
  request.videoPlayerHeight = 480;
  request.videoPlayerWidth = 640;
  request.willAdAutoPlay = PALFlagOn;
  request.willAdPlayMuted = PALFlagOff;

  if (self.nonceManager) {
    // Detach the old nonce manager's gesture recognizer before destroying it.
    [self.videoView removeGestureRecognizer:self.nonceManager.gestureRecognizer];
    self.nonceManager = nil;
  }
  [self.nonceLoader loadNonceManagerWithRequest:request];
}

Cuối cùng, hãy điền dữ liệu uỷ quyền của trình tải số chỉ dùng một lần vào nhật ký số chỉ dùng một lần do nhật ký tạo:

#pragma mark - PALNonceLoaderDelegate methods

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
            withRequest:(PALNonceRequest *)request
    didLoadNonceManager:(PALNonceManager *)nonceManager {
  NSLog(@"Programmatic access nonce: %@", nonceManager.nonce);
  // Capture the created nonce manager and attach its gesture recognizer to the video view.
  self.nonceManager = nonceManager;
  [self.videoView addGestureRecognizer:self.nonceManager.gestureRecognizer];
}

- (void)nonceLoader:(PALNonceLoader *)nonceLoader
         withRequest:(PALNonceRequest *)request
    didFailWithError:(NSError *)error {
  NSLog(@"Error generating programmatic access nonce: %@", error);
}

Khi thực hiện lệnh gọi VAST (DVC) trực tiếp, hãy đặt số chỉ dùng một lần làm giá trị trên Tham số givn. Số chỉ dùng một lần an toàn với URL – bạn không cần phải mã hoá URL.

Thận trọng: Nếu trước đây bạn đã cung cấp một số chỉ dùng một lần bằng tham số paln, thì bạn nên di chuyển sang givn và ngừng gửi paln. Nếu cả hai tham số được bao gồm, đó là hành vi không xác định liên quan đến việc số chỉ dùng một lần nào là sử dụng.

Cuối cùng, bạn cần thêm các phương thức để xử lý việc gửi phiên phát nội dung thông tin và số lần nhấp vào SDK. Hãy xem ví dụ sau đây khi triển khai phương thức sendPlaybackStart, sendPlaybackEnd và sendAdClick:

...

// Reports the start of playback for the current content session.
- (void)sendPlaybackStart {
  [self.nonceManager sendPlaybackStart];
}

// Reports the end of playback for the current content session.
- (void)sendPlaybackEnd {
  [self.nonceManager sendPlaybackEnd];
}

// Reports an ad click for the current nonce manager, if not nil.
- (void)sendAdClick {
  [self.nonceManager sendAdClick];
}

Trong quá trình triển khai, sendPlaybackStart sẽ được gọi trên "trình phát video bắt đầu" khi quá trình phát bắt đầu lần đầu tiên, để phản hồi một hành động do người dùng thực hiện (nhấp để phát) hoặc hành động do ứng dụng thực hiện (tự động phát), sendPlaybackEnd phải được gọi khi quá trình phát kết thúc và sendAdClick phải được gọi mỗi khi người xem nhấp vào một quảng cáo.

(Không bắt buộc) Gửi tín hiệu Google Ad Manager thông qua máy chủ quảng cáo của bên thứ ba

Định cấu hình yêu cầu của máy chủ quảng cáo bên thứ ba cho Ad Manager. Sau khi hoàn tất các bước sau, thông số số chỉ dùng một lần được truyền từ SDK PAL, thông qua các máy chủ trung gian rồi đến Google Ad Manager. Điều này cho phép kiếm tiền hiệu quả hơn thông qua Google Ad Manager.

Lưu ý: Nếu bạn sử dụng nhiều giải pháp của bên thứ ba, chẳng hạn như một giải pháp của bên thứ ba Máy chủ SSAI gọi một máy chủ quảng cáo bên thứ ba khác, bạn cần phải đảm bảo rằng PAL Số chỉ dùng một lần đã mã hoá của SDK được chuyển tiếp đến từng bên thứ ba.

Định cấu hình máy chủ quảng cáo của bên thứ ba để đưa số chỉ dùng một lần vào yêu cầu cho Ad Manager. Dưới đây là ví dụ về một thẻ quảng cáo được định cấu hình bên trong máy chủ quảng cáo của bên thứ ba:

https://pubads.serverside.net/gampad/ads?givn=%%custom_key_for_google_nonce%%&...

Để biết thêm thông tin chi tiết, hãy xem phần triển khai phía máy chủ Google Ad Manager hướng dẫn.

Ad Manager tìm givn= để xác định giá trị số chỉ dùng một lần. Quảng cáo của bên thứ ba máy chủ cần hỗ trợ một số macro của riêng mình, chẳng hạn như %%custom_key_for_google_nonce%% rồi thay thế bằng tham số truy vấn số chỉ dùng một lần mà bạn đã cung cấp ở bước trước. Thông tin khác về cách thực hiện việc này cần có trong tài liệu của máy chủ quảng cáo bên thứ ba.