Xoay vòng mẫu quảng cáo bằng API URL chọn lọc

Sử dụng Select URL API để tận dụng Shared Storage nhằm xác định mẫu quảng cáo mà người dùng nhìn thấy trên các trang web.

Nhà quảng cáo hoặc nhà sản xuất nội dung có thể muốn áp dụng các chiến lược xoay vòng nội dung khác nhau cho một chiến dịch và xoay vòng nội dung hoặc mẫu quảng cáo để tăng hiệu quả. Bạn có thể sử dụng API Chọn URL để chạy nhiều chiến lược xoay vòng, chẳng hạn như xoay vòng tuần tự và xoay vòng phân bổ đều, trên nhiều trang web.

Với tính năng xoay vòng mẫu quảng cáo Select URL API, bạn có thể lưu trữ dữ liệu (chẳng hạn như mã mẫu quảng cáo, số lượt xem và hoạt động tương tác của người dùng) để xác định mẫu quảng cáo mà người dùng nhìn thấy trên nhiều trang web.

Để biết thêm thông tin về API cơ bản và cách hoạt động của quy trình chọn, hãy khám phá tài liệu về Select URL API.

Thử xoay vòng mẫu quảng cáo

Để thử nghiệm tính năng xoay vòng mẫu quảng cáo, hãy nhớ bật Select URL API và Shared Storage:

• Trong chrome://settings/content/siteData, hãy chọn Allow sites to save data on your device hoặc Delete data sites have saved to your device when you close all windows.
• Trong chrome://settings/adPrivacy/sites, hãy chọn Site-suggested ads.

Hãy dùng thử bản minh hoạ trực tiếp về Shared Storage để xem phiên bản trực tiếp của các đoạn mã mẫu trong tài liệu này.

Bản minh hoạ có mã mẫu

Trong ví dụ này:

• creative-rotation.js là tập lệnh của bên thứ ba xác định nội dung cần xoay, cùng với mọi dữ liệu xác định nội dung tiếp theo cần chọn và hiển thị, chẳng hạn như trọng số trong ví dụ này. Trang của nhà xuất bản thực thi tập lệnh này. Tập lệnh này gọi worklet của bộ nhớ dùng chung để xác định nội dung cần hiển thị dựa trên dữ liệu có sẵn trong bộ nhớ và danh sách URL để chọn.

• creative-rotation-worklet.js là worklet bộ nhớ dùng chung của bên thứ ba, có chức năng tra cứu chiến lược xoay vòng, tính toán nội dung cần xuất bản tiếp theo và trả về phần nội dung đó.

Cách hoạt động của bản minh hoạ

1. Khi người dùng truy cập vào trang của nhà xuất bản, trang này sẽ tải tập lệnh creative-rotation.js của bên thứ ba. Tập lệnh xoay vòng mẫu quảng cáo chịu trách nhiệm tải và chạy worklet bộ nhớ dùng chung. Tập lệnh cung cấp cho lệnh gọi worklet một danh sách các URL để chọn.
2. Trong worklet, nếu bộ nhớ dùng chung chưa được khởi chạy, thì bộ nhớ sẽ được khởi chạy bằng chỉ mục mẫu quảng cáo và chiến lược xoay vòng mẫu quảng cáo ban đầu. Chiến lược xoay ban đầu được dùng trong bản minh hoạ này là chiến lược tuần tự.
3. Worklet đọc chế độ xoay vòng từ bộ nhớ dùng chung và trả về chỉ mục của quảng cáo tiếp theo. Trong trường hợp chế độ xoay tuần tự, chế độ này cũng cập nhật chỉ mục mẫu quảng cáo trong bộ nhớ dùng chung bằng giá trị mới sẽ được dùng cho lệnh gọi tiếp theo.Worklet trả về một đối tượng FencedFrameConfig hoặc URN mờ dựa trên giá trị resolveToConfig được dùng khi gọi selectURL.
4. Tập lệnh xoay vòng mẫu quảng cáo sẽ hiển thị quảng cáo đã chọn trong một Khung được rào chắn hoặc một iframe. Hãy xem tài liệu về cách hiển thị quảng cáo để biết thông tin chi tiết về các loại giá trị trả về.
5. Khi người dùng thay đổi chế độ xoay, worklet lưu trữ dùng chung sẽ cập nhật giá trị chế độ xoay mẫu quảng cáo được lưu trữ trong bộ nhớ dùng chung.
6. Khi tải lại trang của nhà xuất bản, các bước 1 đến 4 sẽ được lặp lại, cho phép chọn quảng cáo tiếp theo sẽ được xem dựa trên chiến lược xoay vòng đã chọn

Mã mẫu

Sau đây là các mẫu mã cho creative-rotation.js và creative-rotation-worklet.js.

creative-rotation.js

const contentProducerUrl = 'https://your-server.example';

// Ad config with the URL of the ad, a probability weight for rotation, and the clickthrough rate.
const DEMO_AD_CONFIG = [
  {
    url: `${contentProducerUrl}/ads/ad-1.html`,
    weight: 0.7,
  },
  {
    url: `${contentProducerUrl}/ads/ad-2.html`,
    weight: 0.2,
  },
  {
    url: `${contentProducerUrl}/ads/ad-3.html`,
    weight: 0.1,
  },
];

async function setRotationMode(rotationMode) {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  await creativeRotationWorklet.run('set-rotation-mode', {
    data: { rotationMode }
  });
  console.log(`creative rotation mode set to ${rotationMode}`);
}

async function injectAd() {
  // Load the worklet module
  const creativeRotationWorklet = await window.sharedStorage.createWorklet(
    `${contentProducerUrl}/url-selection/creative-rotation-worklet.js`,
    { dataOrigin: 'script-origin' }
  );

  const urls = DEMO_AD_CONFIG.map(({ url }) => ({ url }));

  // Resolve the selectURL call to a fenced frame config only when it exists on the page
  const resolveToConfig = typeof window.FencedFrameConfig !== 'undefined';

  // Run the URL selection operation to determine the next ad that should be rendered
  const selectedUrl = await creativeRotationWorklet.selectURL('creative-rotation', urls, {
    data: DEMO_AD_CONFIG,
    resolveToConfig
  });

  const adSlot = document.getElementById('ad-slot');

  if (resolveToConfig && selectedUrl instanceof FencedFrameConfig) {
    adSlot.config = selectedUrl;
  } else {
    adSlot.src = selectedUrl;
  }
}

injectAd();

creative-rotation-worklet.js

class SelectURLOperation {
  async run(urls, data) {
    // Initially set the storage to sequential mode for the demo
    await SelectURLOperation.seedStorage();

    // Read the rotation mode from Shared Storage
    const rotationMode = await sharedStorage.get('creative-rotation-mode');

    // Generate a random number to be used for rotation
    const randomNumber = Math.random();

    let index;

    switch (rotationMode) {
      /**
       * Sequential rotation
       * - Rotates the creatives in order
       * - Example: A -> B -> C -> A ...
       */
      case 'sequential':
        const currentIndex = await sharedStorage.get('creative-rotation-index');
        index = parseInt(currentIndex, 10);
        const nextIndex = (index + 1) % urls.length;

        console.log(`index = ${index} / next index = ${nextIndex}`);

        await sharedStorage.set('creative-rotation-index', nextIndex.toString());
        break;

      /**
       * Evenly-distributed rotation
       * - Rotates the creatives with equal probability
       * - Example: A=33% / B=33% / C=33%
       */
      case 'even-distribution':
        index = Math.floor(randomNumber * urls.length);
        break;

      /**
       * Weighted rotation
       * - Rotates the creatives with weighted probability
       * - Example: A=70% / B=20% / C=10%
       */
      case 'weighted-distribution':
        console.log('data = ', JSON.stringify(data));
        // Find the first URL where the cumnulative sum of the weights
        // exceed the random number. The array is sorted by the weight
        // in descending order.
        let weightSum = 0;
        const { url } = data
          .sort((a, b) => b.weight - a.weight)
          .find(({ weight }) => {
            weightSum += weight;
            return weightSum > randomNumber;
          });

        index = urls.indexOf(url);
        break;

      default:
        index = 0;
    }

    console.log(JSON.stringify({ index, randomNumber, rotationMode }));
    return index;
  }

  // Set the mode to sequential and set the starting index to 0.
  static async seedStorage() {
    await sharedStorage.set('creative-rotation-mode', 'sequential', {
      ignoreIfPresent: true,
    });

    await sharedStorage.set('creative-rotation-index', 0, {
      ignoreIfPresent: true,
    });
  }
}

class SetRotationModeOperation {
  async run({ rotationMode }) {
    await sharedStorage.set('creative-rotation-mode', rotationMode);
  }
}

// Register the operation as 'creative-rotation'
register('creative-rotation', SelectURLOperation);
register('set-rotation-mode', SetRotationModeOperation);

Hướng dẫn từng bước kèm ảnh chụp màn hình

1. Để truy cập vào tính năng Xoay mẫu quảng cáo bằng Select URL API và Bộ nhớ dùng chung, hãy truy cập vào https://shared-storage-demo.web.app/. Chọn bản minh hoạ "Xoay vòng mẫu quảng cáo".

2. Chọn khám phá bản minh hoạ với tư cách là "Nhà xuất bản A". Bạn sẽ được chuyển hướng đến https://shared-storage-demo-publisher-a.web.app/creative-rotation. Trang này tải nội dung được đánh số dựa trên dữ liệu xoay vòng mẫu quảng cáo được lưu trong Shared Storage, truy cập thông qua Select URL API. Các chế độ minh hoạ cho tính năng xoay vòng mẫu quảng cáo là tuần tự, phân phối đồng đều và phân phối theo trọng số. Worklet thực thi logic để chọn nội dung xuất hiện trong iframe. Hình ảnh sau đây cho thấy trang của nhà xuất bản.

   
   

3. Để xem nội dung được lưu trữ trong Shared Storage, hãy chuyển đến Application (Ứng dụng) -> Shared Storage (Bộ nhớ dùng chung) trong Chrome DevTools. Hai mục được tạo cho bộ nhớ dùng chung. Có một bộ nhớ trống cho nguồn https://shared-storage-demo-publisher-a.web.app. Thư mục này sẽ chứa bộ nhớ dành riêng cho nguồn gốc đó và sẽ vẫn trống đối với bản minh hoạ của chúng tôi vì nhà xuất bản không cần ghi vào bộ nhớ dùng chung. Xin lưu ý rằng một bộ nhớ tương tự sẽ được tạo cho Nhà xuất bản B khi bạn truy cập vào trang đó vào thời điểm khác cho bản minh hoạ.

   
   

4. Một mục Shared Storage khác sẽ được tạo cho nguồn https://shared-storage-demo-content-producer.web.app. Đây là bộ nhớ của iframe bên thứ ba được nhúng trên trang của nhà xuất bản. Bộ nhớ này sẽ được dùng để chia sẻ dữ liệu giữa hai nhà xuất bản có sẵn nhằm điều phối việc chọn mẫu quảng cáo. Bộ nhớ dùng chung này sẽ được dùng để lưu thông tin về mẫu quảng cáo đã hiển thị và chiến lược xoay vòng bằng cách lưu 2 cặp khoá-giá trị. Khoá đầu tiên được dùng trong bản minh hoạ là creative-rotation-index, có giá trị là chỉ mục mẫu quảng cáo hiện tại ở chế độ tuần tự. Khoá thứ hai là creative-rotation-mode, khoá này quy định chiến lược xoay vòng được sử dụng.

   
   

5. Việc làm mới trang khi ở chế độ tuần tự sẽ dẫn đến việc hiển thị mẫu quảng cáo tiếp theo theo trình tự 1, 2, 3, 1, ... Giá trị cho khoá creative-rotation-index sẽ thay đổi theo chỉ mục của mẫu quảng cáo được hiển thị khi ở chế độ tuần tự.

   
   

6. Việc thay đổi chế độ xoay vòng mẫu quảng cáo bằng các nút điều khiển sẽ cập nhật giá trị cho khoá creative-rotation-mode thành chiến lược tương ứng. Mã worklet sẽ dùng thông tin này để chọn mẫu quảng cáo tiếp theo sẽ xuất hiện trong iframe. Xin lưu ý rằng giá trị được lưu cho creative-rotation-index không thay đổi đối với các chế độ xoay khác ngoài chế độ tuần tự.

   
   

7. Chuyển đến trang của "Nhà xuất bản B" tại https://shared-storage-demo-publisher-b.web.app/creative-rotation. Ở chế độ tuần tự, mẫu quảng cáo được hiển thị phải là mẫu quảng cáo tiếp theo trong chuỗi được hiển thị khi truy cập vào URL của "Nhà xuất bản A". Khi kiểm tra Bộ nhớ dùng chung của nhà sản xuất nội dung, bạn có thể thấy rằng cả "Nhà xuất bản A" và "Nhà xuất bản B" đều dùng chung bộ nhớ và đang sử dụng các chế độ cài đặt ở đó để chọn mẫu quảng cáo tiếp theo sẽ hiển thị và chiến lược xoay vòng sẽ sử dụng.

   
   

8. Shared Storage của "Nhà xuất bản B" không có dữ liệu, tương tự như Shared Storage của "Nhà xuất bản A".

   
   

   Trường hợp sử dụng

   Bạn có thể xem tất cả các trường hợp sử dụng hiện có cho API Chọn URL trong phần này. Chúng tôi sẽ tiếp tục thêm ví dụ khi nhận được ý kiến phản hồi và khám phá các trường hợp kiểm thử mới.

   • Xoay vòng mẫu quảng cáo: Lưu trữ dữ liệu, chẳng hạn như mã mẫu quảng cáo và lượt tương tác của người dùng, để xác định mẫu quảng cáo mà người dùng nhìn thấy trên các trang web.
   • Chọn mẫu quảng cáo theo tần suất: Sử dụng dữ liệu về số lượt xem để xác định mẫu quảng cáo mà người dùng nhìn thấy trên các trang web.
   • Chạy thử nghiệm A/B: Bạn có thể chỉ định người dùng cho một nhóm thử nghiệm, sau đó lưu trữ nhóm đó trong Bộ nhớ dùng chung để truy cập trên nhiều trang web.
   • Tuỳ chỉnh trải nghiệm cho khách hàng đã biết: Chia sẻ nội dung tuỳ chỉnh và lời kêu gọi hành động dựa trên trạng thái đăng ký của người dùng hoặc các trạng thái khác của người dùng.

Tương tác và chia sẻ ý kiến phản hồi

Xin lưu ý rằng đề xuất về Select URL API đang được thảo luận và phát triển tích cực, vì vậy, đề xuất này có thể thay đổi.

Chúng tôi rất mong được biết ý kiến của bạn về Select URL API.

• Đề xuất: Xem xét đề xuất chi tiết.
• Thảo luận: Tham gia cuộc thảo luận đang diễn ra để đặt câu hỏi và chia sẻ hiểu biết của bạn.