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à theo dõi các sự kiện phát. Để làm theo hướng dẫn hoàn chỉnh, hãy tải ứng dụng mẫu PAL tvOS.

Thêm SDK PAL vào dự á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ợ Trình quản lý gói Swift kể từ phiên bản 2.5.3. Hãy làm theo các bước dưới đây để nhập gói Swift.

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

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

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

3. Chọn phiên bản Gói Swift SDK PAL bạn muốn sử dụng. Đối với các dự án mới, bạn nên sử dụng tính năng Lên đế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 các phần phụ thuộc đó xuống trong nền. Để biết thêm thông tin chi tiết về cách thêm các phần phụ thuộc của gói, 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 rồi thêm SDK PAL vào dự á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

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

Tất cả các đoạn mã dưới đây đều 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 thực thể của lớp 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. Thao tác này sẽ giữ nguyên tham số tương quan trang hoặc tham số &correlator trong suốt thời gian hoạt động của trang hoặc phiên hoạt động của người dùng ứng dụng.

Bạn vẫn có quyền kiểm soát đối với giá trị tương quan của luồng, hoặc &scor. Bạn nên đặt lại các giá trị này 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 phải chia sẻ cùng một PALNonceLoader và giá trị tương quan của luồng để giới hạn tần suất và tính năng loại trừ cạnh tranh để hoạt động đúng cách.

Tiếp theo, hãy tạo một thực thể của PALNonceLoader và thêm các mã giả lập cho 2 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 bắt đầu một yêu cầu số chỉ dùng một lần, điền sẵn các thuộc tính của nó và sử dụng yêu cầu đó để khởi động 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.
 */
- (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 uỷ quyền 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 đã 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 trực tiếp (DVC), 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 là an toàn cho URL – bạn không cần phải mã hoá URL.

Thận trọng: Nếu trước đây đã cung cấp một số chỉ dùng một lần bằng tham số paln, bạn nên di chuyển sang givn và ngừng gửi paln. Nếu bạn đưa cả hai tham số vào, thì đó sẽ là hành vi không xác định liên quan đến số chỉ dùng một lần được 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 thông tin về phiên phát nội dung và các lượt nhấp vào SDK. Hãy xem ví dụ sau đây về cách triển khai các 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 phải được gọi khi "bắt đầu trình phát video" khi quá trình phát bắt đầu lần đầu tiên, để phản hồi hành động do người dùng khởi tạo (nhấp để phát) hoặc hành động do ứng dụng khởi tạo (tự động phát), sendPlaybackEnd sẽ được gọi khi kết thúc phát và sendAdClick sẽ được gọi mỗi khi người xem nhấp vào 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 đối với Ad Manager. Sau khi bạn hoàn tất các bước sau, tham số số chỉ dùng một lần sẽ truyền từ SDK PAL, thông qua các máy chủ trung gian của bạn rồi đến Google Ad Manager. Điều này giúp bạn kiếm tiền hiệu quả hơn thông qua Google Ad Manager.

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

Định cấu hình máy chủ quảng cáo bên thứ ba để đưa số chỉ dùng một lần vào yêu cầu của máy chủ đối với 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 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 Hướng dẫn triển khai phía máy chủ của Google Ad Manager.

Ad Manager tìm givn= để xác định giá trị số chỉ dùng một lần. Máy chủ quảng cáo bên thứ ba cần hỗ trợ một số macro của riêng mình, chẳng hạn như %%custom_key_for_google_nonce%% và 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. Bạn nên xem thêm thông tin về cách thực hiện việc này trong tài liệu của máy chủ quảng cáo bên thứ ba.