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 PAL SDK để nhận một 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 xuống.

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

Cài đặt PAL SDK 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 từ phiên bản 2.5.3. Hãy 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 Swift SDK IMA bằng cách chuyển đến File (Tệp) > Add Packages (Thêm gói)....

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

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

3. Chọn phiên bản của 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 lớn tiếp theo.

Sau khi bạn hoàn tất, Xcode sẽ phân giải các phần phụ thuộc của gói và tải các phần phụ thuộc đó xuống ở chế độ 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 và cài đặt SDK PAL theo cách thủ công

Nếu không muốn sử dụng Swift Package Manager, bạn có thể tải PAL SDK xuống và thêm SDK này vào dự án theo cách thủ công.

1. Tải và trích xuất PAL SDK cho tvOS
2. Hãy làm theo Hướng dẫn cho nhà phát triển của Apple để kết 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 được mã hoá duy nhất do PAL tạo bằng cách sử dụng PALNonceLoader. PAL SDK yêu cầu mỗi yêu cầu phát trực tuyến mới phả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ể 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ã bên dưới đề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 phiên bản 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 giữ cho thông số tương quan trang (hoặc thông số &correlator) không thay đổi trong suốt thời gian tồn tại của một trang hoặc phiên hoạt động của người dùng trên ứng dụng.

Bạn vẫn có quyền kiểm soát bộ tương quan luồng hoặc &scor. Bộ tương quan này sẽ được đặ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 phát phải dùng chung cùng một giá trị PALNonceLoader và giá trị tương quan luồng phát để các tính năng giới hạn tần suất và 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 phần giữ chỗ 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 'directedForChildOrUnknownAge' is
  // 'NO'. Update the value after the appropriate consent has been gathered.
  // By default, PAL automatically determines whether to enable limited ads
  // based on the user's TCF (Transparency and Consent Framework) consent data
  // on the device. If you must manually override the default behavior,
  // for example, to meet your app's requirements, use the
  // `PALSettings.forceLimitedAds` property.
  PALSettings *settings = [[PALSettings alloc] init];
  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 yêu cầu đó và dùng yêu cầu đó để khởi chạy một 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 integers. See reference docs for more details.
  request.supportedAPIFrameworks = [NSMutableSet setWithArray:@[ @2, @7, @9 ]];
  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 thông tin về các uỷ quyền của trình tải số chỉ dùng một lần để ghi lại các 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 an toàn cho URL – bạn không cần mã hoá số này thành URL.

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

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à lượt nhấp của phiên phát nội dung đến SDK. Hãy xem ví dụ sau đây 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 sẽ được gọi khi "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 bắt đầu (nhấp để phát) hoặc một hành động do ứng dụng bắt đầu (tự động phát), sendPlaybackEnd sẽ được gọi khi quá trình phát kết thúc và sendAdClick sẽ đượ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 đố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ừ PAL SDK, 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 (ví dụ: máy chủ SSAI của bên thứ ba gọi một máy chủ quảng cáo khác của bên thứ ba), bạn cần đảm bảo rằng số chỉ dùng một lần được mã hoá của PAL 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 của máy chủ đối với Ad Manager. Dưới đây là ví dụ về thẻ quảng cáo được định cấu hình 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 Hướng dẫn triển khai phía máy chủ của Google Ad Manager.

Ad Manager tìm kiế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 có thể 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.