با استفاده از Protected Audience API از هدف گیری مخاطبان سفارشی پشتیبانی کنید

bookmark_border با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

به روز رسانی های اخیر

• اطلاعاتی درباره زمان‌بندی به‌روزرسانی‌های سفارشی مخاطبان اضافه شد
• افزودن یکپارچه سازی Attribution Reporting با مخاطبان محافظت شده
• جدول زمانی ویژگی‌های مخاطب محافظت شده را منتشر کرد.
• FLEDGE به API مخاطب محافظت شده تغییر نام داده است.
• پیشنهاد برای تفویض اختیار مخاطبان سفارشی اضافه شد.
• الزام ناشناس بودن k برای URL به‌روزرسانی روزانه حذف شد.

مخاطب محافظت شده در نسخه بتا است و برای آزمایش در دستگاه های عمومی در دسترس است!

با مخاطبین محافظت شده، می توانید:

• مخاطبان سفارشی را بر اساس اقدامات قبلی کاربر مدیریت کنید.
• حراج‌های روی دستگاه را با پشتیبانی از میانجی‌گری تک فروشنده یا آبشار آغاز کنید.
• پس از انتخاب آگهی، گزارش نمایش را تمرین کنید.

برای شروع، راهنمای برنامه‌نویس مخاطب محافظت شده را بخوانید. با ادامه توسعه مخاطبین محافظت شده، از بازخورد شما قدردانی می شود.

جدول زمانی

ما ویژگی های جدید را در ماه های آینده منتشر خواهیم کرد. تاریخ انتشار دقیق بسته به ویژگی متفاوت خواهد بود و این جدول با در دسترس قرار گرفتن با پیوندهایی به اسناد به روز می شود.

نمای کلی

در تبلیغات تلفن همراه، تبلیغ‌کنندگان معمولاً باید بر اساس نحوه تعامل قبلی با برنامه تبلیغ‌کننده، تبلیغات را به کاربران بالقوه علاقه‌مند ارائه دهند. برای مثال، توسعه‌دهنده SportingGoodsApp ممکن است بخواهد برای کاربرانی که مواردی را در سبد خرید باقی مانده‌اند، با نمایش تبلیغات برای یادآوری به کاربران برای تکمیل خرید تبلیغ کند. صنعت معمولاً این ایده کلی را با عباراتی مانند "بازاریابی مجدد" و "هدف گیری مخاطبان سفارشی" توصیف می کند.

امروزه، این موارد استفاده معمولاً با به اشتراک گذاشتن اطلاعات زمینه‌ای درباره نحوه نمایش آگهی (مانند نام برنامه) و اطلاعات خصوصی مانند فهرست‌های مخاطبان با پلتفرم‌های فناوری تبلیغات اجرا می‌شوند. با استفاده از این اطلاعات، تبلیغ‌کنندگان می‌توانند تبلیغات مرتبط را در سرورهای خود انتخاب کنند.

API مخاطب محافظت شده در Android (که قبلاً به عنوان FLEDGE شناخته می شد) شامل API های زیر برای پلتفرم های فناوری تبلیغات و تبلیغ کنندگان است تا از موارد استفاده مبتنی بر تعامل متداول پشتیبانی کند به گونه ای که اشتراک گذاری هر دو شناسه در بین برنامه ها و اطلاعات تعامل برنامه کاربر با شخص ثالث را محدود می کند:

1. API مخاطبان سفارشی : این بر انتزاع "مخاطبان سفارشی" متمرکز است که نشان دهنده مخاطبان تعیین شده توسط تبلیغ کننده با اهداف مشترک است. اطلاعات مخاطب در دستگاه ذخیره می‌شود و می‌تواند با تبلیغات نامزد مربوطه برای مخاطبان و فراداده‌های دلخواه، مانند سیگنال‌های پیشنهادی مرتبط شود. از این اطلاعات می توان برای اطلاع رسانی پیشنهادات آگهی دهنده، فیلتر کردن آگهی و رندر استفاده کرد.
2. Ad Selection API : این چارچوبی را ارائه می‌کند که گردش‌های کاری پلت‌فرم‌های فناوری تبلیغات را تنظیم می‌کند که از سیگنال‌های روی دستگاه برای تعیین یک آگهی «برنده» با در نظر گرفتن تبلیغات نامزد ذخیره‌شده در محلی، و انجام پردازش اضافی بر روی تبلیغات نامزدی که یک پلت‌فرم فناوری تبلیغات به دستگاه بازمی‌گرداند، استفاده می‌کند.

در سطح بالا، ادغام به شرح زیر عمل می کند:

1. SportingGoodsApp می‌خواهد به کاربران خود یادآوری کند که اگر در عرض 2 روز خرید را انجام ندادند، کالاهای موجود در سبد خرید خود را خریداری کنند. SportingGoodsApp از Custom Audience API برای اضافه کردن کاربر به لیست مخاطبان "محصولات در سبد خرید" استفاده می کند. پلتفرم این فهرست مخاطبان را در دستگاه مدیریت و ذخیره می‌کند و اشتراک‌گذاری با اشخاص ثالث را محدود می‌کند. SportingGoodsApp با یک پلت فرم فناوری تبلیغات شریک می شود تا تبلیغات خود را به کاربران در لیست مخاطبان خود نشان دهد. پلتفرم فناوری تبلیغات، ابرداده‌ها را برای فهرست‌های مخاطبان مدیریت می‌کند و تبلیغات نامزد را ارائه می‌کند، که برای بررسی در اختیار گردش کار انتخاب آگهی قرار می‌گیرد. این پلت فرم را می توان به گونه ای پیکربندی کرد که به صورت دوره ای آگهی های به روز شده مبتنی بر مخاطب را در پس زمینه دریافت کند . این کمک می کند تا لیست تبلیغات نامزد مبتنی بر مخاطبان تازه و نامرتبط با درخواست های ارسال شده به سرورهای تبلیغاتی شخص ثالث در طول فرصت تبلیغات (یعنی درخواست آگهی متنی) باقی بماند.

2. هنگامی که کاربر FrisbeeGame را در همان دستگاه بازی می‌کند، ممکن است تبلیغی را ببیند که به او یادآوری می‌کند تا خرید اقلام باقی‌مانده در سبد خرید SportingGoodsApp را تکمیل کند. این را می توان با استفاده از FrisbeeGame (با یک SDK تبلیغات یکپارچه) با فراخوانی Ad Selection API برای انتخاب یک تبلیغ برنده برای کاربر بر اساس هر فهرست مخاطبانی که ممکن است بخشی از آن باشند (در این مثال، "محصولات در سبد خرید" مخاطبان سفارشی ایجاد شده توسط SportingGoodsApp) به دست آورد. گردش کار انتخاب آگهی را می توان به گونه ای تنظیم کرد که تبلیغات بازیابی شده از سرورهای پلتفرم های فناوری تبلیغات، علاوه بر تبلیغات روی دستگاه مرتبط با مخاطبان سفارشی و همچنین سایر سیگنال های روی دستگاه را در نظر بگیرد. گردش کار همچنین می‌تواند توسط پلتفرم فناوری تبلیغات و SDK تبلیغات با پیشنهاد سفارشی و منطق امتیازدهی برای دستیابی به اهداف تبلیغاتی مناسب سفارشی شود. این رویکرد علاقه کاربر یا داده‌های تعامل برنامه را قادر می‌سازد تا از انتخاب تبلیغات مطلع شود، در حالی که اشتراک‌گذاری این داده‌ها با اشخاص ثالث را محدود می‌کند.

3. برنامه ارائه آگهی یا SDK پلت فرم فناوری تبلیغات، آگهی انتخابی را ارائه می دهد.

4. این پلت فرم گزارش برداشت ها و نتایج انتخاب آگهی را تسهیل می کند. این قابلیت گزارش‌دهی مکمل API Attribution Reporting است. پلتفرم‌های فناوری تبلیغات ممکن است بر اساس نیازهای گزارش‌دهی خود سفارشی‌سازی کنند.

در APIهای Android به مخاطبین محافظت شده دسترسی پیدا کنید

پلتفرم‌های فناوری تبلیغات برای دسترسی به API مخاطبان محافظت‌شده باید ثبت‌نام کنند. برای اطلاعات بیشتر به ثبت نام برای یک حساب Sandbox حریم خصوصی مراجعه کنید.

مدیریت مخاطبان سفارشی

مخاطب سفارشی

یک مخاطب سفارشی نشان دهنده گروهی از کاربران است که توسط تبلیغ کننده با اهداف یا علایق مشترک تعیین شده است. یک برنامه یا SDK ممکن است از یک مخاطب سفارشی برای نشان دادن یک مخاطب خاص استفاده کند، مانند شخصی که "اقلامی را در سبد خرید خود گذاشته است" یا "سطوح مبتدی" یک بازی را تکمیل کرده است. این پلتفرم اطلاعات مخاطبین را به صورت محلی در دستگاه نگهداری و ذخیره می‌کند و نشان نمی‌دهد که کاربر در کدام مخاطبان سفارشی قرار دارد. مخاطبان سفارشی از گروه‌های علاقه مخاطب محافظت‌شده Chrome متمایز هستند و نمی‌توان آنها را در وب و برنامه‌ها به اشتراک گذاشت. این به محدود کردن اشتراک گذاری اطلاعات کاربر کمک می کند.

یک برنامه تبلیغ‌کننده یا SDK یکپارچه ممکن است به یک مخاطب سفارشی بپیوندد یا بر اساس مشارکت کاربر در یک برنامه، به عنوان مثال، آن را ترک کند .

فراداده مخاطب سفارشی

هر مخاطب سفارشی حاوی متادیتای زیر است:

• مالک: نام بسته برنامه مالک. این به طور ضمنی روی نام بسته برنامه تماس گیرنده تنظیم شده است.
• خریدار: شبکه تبلیغاتی خریدار که تبلیغات را برای این مخاطبان سفارشی مدیریت می کند. خریدار همچنین نماینده طرفی است که ممکن است به مخاطبان سفارشی دسترسی داشته باشد و اطلاعات مربوط به آگهی را دریافت کند. خریدار طبق فرمت eTLD+1 مشخص شده است.
• نام: یک نام یا شناسه دلخواه برای مخاطبان سفارشی، مانند کاربری که دارای «رهاکننده سبد خرید» است. این ویژگی می‌تواند به‌عنوان مثال، به‌عنوان یکی از معیارهای هدف‌یابی در کمپین‌های تبلیغاتی تبلیغ‌کننده، یا یک رشته جستجو در URL برای واکشی کد مناقصه استفاده شود.
• زمان فعال سازی و زمان انقضا: این فیلدها پنجره زمانی را مشخص می کنند که این مخاطبان سفارشی موثر خواهند بود. این پلتفرم از این اطلاعات برای حذف عضویت از مخاطبان سفارشی استفاده می کند. زمان انقضا برای محدود کردن عمر مخاطب سفارشی نمی تواند از حداکثر پنجره مدت تجاوز کند.
• URL به روز رسانی روزانه: نشانی اینترنتی که پلتفرم برای واکشی تبلیغات نامزد و سایر ابرداده‌های تعریف شده در فیلدهای «سیگنال‌های مناقصه کاربر» و «سیگنال‌های مناقصه قابل اعتماد» به صورت مکرر استفاده می‌کند. برای جزئیات بیشتر، به بخش نحوه واکشی تبلیغات نامزد برای مخاطبان سفارشی مراجعه کنید.
• سیگنال‌های مناقصه کاربر: سیگنال‌های ویژه پلتفرم فناوری تبلیغات برای هرگونه پیشنهاد تبلیغات بازاریابی مجدد. نمونه هایی از سیگنال ها عبارتند از: مکان درشت کاربر، منطقه ترجیحی، و غیره.
• داده‌های پیشنهادی مورد اعتماد: پلتفرم‌های فناوری تبلیغات برای اطلاع‌رسانی به بازیابی آگهی و امتیازدهی به داده‌های هم‌زمان متکی هستند. برای مثال، ممکن است بودجه یک آگهی تمام شود و باید فوراً پخش آن متوقف شود. یک Ad-tech می‌تواند یک نقطه پایانی URL را از جایی که این داده‌های بی‌درنگ واکشی می‌شود و مجموعه کلیدهایی که باید جستجوی بی‌درنگ برای آن‌ها انجام شود، تعریف کند. سروری که این درخواست را مدیریت می کند یک سرور قابل اعتماد خواهد بود که توسط پلت فرم فناوری تبلیغات مدیریت می شود.
• URL منطقی مناقصه: نشانی اینترنتی که پلتفرم از آن برای دریافت کد مناقصه از پلتفرم سمت تقاضا استفاده می کند. پلتفرم این مرحله را زمانی انجام می دهد که یک مزایده تبلیغاتی شروع شود .
• تبلیغات: فهرستی از تبلیغات نامزد برای مخاطبان سفارشی. این شامل ابرداده های تبلیغاتی خاص پلتفرم فناوری تبلیغات و یک URL برای ارائه آگهی است. هنگامی که یک حراج برای مخاطبان سفارشی آغاز می شود، این لیست از ابرداده های آگهی در نظر گرفته می شود. در صورت امکان، این لیست از تبلیغات با استفاده از نقطه پایانی URL به روز رسانی روزانه به روز می شود. به دلیل محدودیت منابع در دستگاه های تلفن همراه، محدودیتی در تعداد تبلیغاتی که می توان در یک مخاطب سفارشی ذخیره کرد وجود دارد.

هیئت مخاطبان سفارشی

تعریف و پیکربندی مخاطب سفارشی سنتی معمولاً به فناوری‌ها و ادغام‌های سمت سرور متکی است که توسط فناوری‌های تبلیغاتی در مشارکت با مشتریان و شرکای آژانس و تبلیغ‌کننده هدایت می‌شوند. Protected Audience API تعریف و پیکربندی مخاطب سفارشی را در عین محافظت از حریم خصوصی کاربر فعال می کند. برای پیوستن به مخاطبان سفارشی، فناوری‌های تبلیغاتی خریدار که در برنامه‌ها حضور SDK ندارند، باید با فناوری‌های تبلیغاتی که در دستگاه حضور دارند، مانند شرکای اندازه‌گیری تلفن همراه (MMP) و پلت‌فرم‌های طرف عرضه (SSP) همکاری کنند. هدف برنامه Protected Audience API پشتیبانی از این SDKها با ارائه راه‌حل‌های انعطاف‌پذیر برای مدیریت مخاطبان سفارشی است که از طریق تماس‌گیرندگان دستگاه امکان ایجاد مخاطب سفارشی از طرف خریداران را فراهم می‌کند. به این فرآیند تفویض اختیار مخاطب سفارشی می گویند. با دنبال کردن این مراحل، تفویض مخاطبان سفارشی را پیکربندی کنید:

به یک مخاطب سفارشی بپیوندید

پیوستن به یک مخاطب سفارشی می تواند به دو صورت انجام شود:

joinCustomAudience()

یک برنامه یا SDK می‌تواند با فراخوانی joinCustomAudience() پس از نمونه‌سازی شی CustomAudience با پارامترهای مورد انتظار، درخواست ملحق شدن به یک مخاطب سفارشی کند. در اینجا یک نمونه قطعه کد گویا آمده است:

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

یک برنامه یا SDK می‌تواند با فراخوانی fetchAndJoinCustomAudience() با پارامترهای مورد انتظار، مانند مثال زیر، از طرف یک فناوری تبلیغاتی که در دستگاه حضور ندارد، درخواست ملحق شدن به یک مخاطب سفارشی کند:

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

نقطه پایانی URL، متعلق به خریدار، با یک شی JSON CustomAudience در بدنه پاسخ پاسخ می دهد. فیلدهای خریدار و مالک مخاطبان سفارشی نادیده گرفته می شوند (و توسط API به صورت خودکار پر می شوند). API همچنین اجبار می‌کند که URL به‌روزرسانی روزانه با eTLD+1 خریدار نیز مطابقت داشته باشد.

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

API fetchAndJoinCustomAudience() هویت خریدار را از eTLD+1 fetchUri تعیین می کند. هویت خریدار CustomAudience برای انجام همان بررسی‌های ثبت‌نام و مجوز برنامه که توسط joinCustomAudience() انجام می‌شود استفاده می‌شود و با پاسخ واکشی قابل تغییر نیست. مالک CustomAudience نام بسته برنامه تماس است. هیچ اعتبارسنجی دیگری به جز چک eTLD+1 برای fetchUri وجود ندارد و به طور خاص، هیچ بررسی k-anon وجود ندارد. API fetchAndJoinCustomAudience() یک درخواست HTTP GET برای fetchUri صادر می کند و انتظار دارد یک شی JSON نماینده مخاطب سفارشی باشد. همان محدودیت‌های اجباری، اختیاری و مقادیر پیش‌فرض برای فیلدهای شی مخاطب سفارشی به پاسخ اعمال می‌شود. در راهنمای برنامه نویس ما با الزامات و محدودیت های فعلی آشنا شوید.

هرگونه پاسخ خطای HTTP از طرف خریدار باعث می شود fetchAndJoinCustomAudience با شکست مواجه شود. به ویژه یک پاسخ وضعیت HTTP 429 (درخواست‌های خیلی زیاد) درخواست‌های برنامه فعلی را برای یک دوره مشخص مسدود می‌کند. اگر پاسخ خریدار بد شکل باشد، تماس API نیز با شکست مواجه می‌شود. خرابی‌ها به تماس‌گیرنده API گزارش می‌شوند که مسئول تلاش مجدد به دلیل خرابی‌های موقتی (مانند پاسخ ندادن سرور) یا مدیریت خرابی‌های مداوم (مانند خرابی‌های اعتبارسنجی داده یا سایر خطاهای غیر گذرا در ارتباط با سرور) هستند.

شی CustomAudienceFetchRequest به تماس گیرنده API اجازه می دهد تا با استفاده از ویژگی های اختیاری نشان داده شده در مثال بالا، برخی از اطلاعات را برای مخاطبان سفارشی تعریف کند. اگر در درخواست تنظیم شده باشد، این مقادیر نمی توانند توسط پاسخ خریدار دریافت شده توسط پلت فرم بازنویسی شوند. Protected Audience API فیلدهای موجود در پاسخ را نادیده می گیرد. اگر در درخواست تنظیم نشده باشند، باید در پاسخ تنظیم شوند، زیرا این فیلدها برای ایجاد یک مخاطب سفارشی مورد نیاز هستند. یک نمایش JSON از محتوای CustomAudience که تا حدی توسط فراخوان API تعریف شده است، در درخواست GET برای fetchUri در یک هدر ویژه X-CUSTOM-AUDIENCE-DATA گنجانده شده است. اندازه فرم سریال داده های مشخص شده برای مخاطبان سفارشی به 8 کیلوبایت محدود شده است. اگر اندازه بیش از اندازه باشد، تماس API fetchAndJoinCustomAudience ناموفق است.

فقدان بررسی k-anon به شما امکان می‌دهد از fetchUri برای تأیید خریدار و فعال کردن اشتراک‌گذاری اطلاعات بین خریدار و SDK استفاده کنید. برای تسهیل راستی‌آزمایی مخاطبان سفارشی، این امکان برای خریدار وجود دارد که یک رمز تأیید ارائه کند. SDK روی دستگاه باید شامل این نشانه در fetchUri باشد تا نقطه پایانی میزبانی شده توسط خریدار بتواند محتویات مخاطبان سفارشی را واکشی کند و از رمز تأیید برای تأیید اینکه عملیات fetchAndJoinCustomAudience() با خریدار مطابقت دارد و از یک شریک قابل اعتماد در دستگاه منشا گرفته است استفاده کند. برای اشتراک‌گذاری اطلاعات، خریدار می‌تواند با تماس‌گیرنده روی دستگاه موافقت کند که برخی از اطلاعات مورد استفاده برای ایجاد مخاطب سفارشی به‌عنوان پارامترهای جستجو به fetchUri اضافه شود. این به خریدار اجازه می‌دهد تا تماس‌ها را بررسی کند و تشخیص دهد که آیا یک نشانه اعتبارسنجی توسط یک فناوری تبلیغات مخرب برای ایجاد چندین مخاطب سفارشی مختلف استفاده شده است یا خیر.

یادداشتی در مورد تعریف رمز تأیید و ذخیره سازی

• کد تأیید برای هیچ هدفی توسط Protected Audience API استفاده نمی شود و اختیاری است.

  • رمز تأیید ممکن است توسط خریدار برای تأیید اینکه مخاطبان ایجاد شده از طرف آنها انجام می شوند استفاده شود.
  • پیشنهاد Protected Audience API نه قالبی برای رمز تأیید و نه نحوه انتقال رمز تأیید توسط خریدار به تماس‌گیرنده مشخص می‌کند. به عنوان مثال، رمز تأیید می‌تواند از قبل در SDK یا باطن مالک بارگذاری شود، یا می‌توان آن را در زمان واقعی توسط SDK مالک از سرور خریدار بازیابی کرد.

یک مخاطب سفارشی بگذارید

صاحب یک مخاطب سفارشی می‌تواند با فراخوانی leaveCustomAudience() را ترک کند، همانطور که در قطعه کد تصویری زیر نشان داده شده است:

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

برای کمک به حفظ استفاده از فضای ذخیره‌سازی و سایر منابع دستگاه، مخاطبان سفارشی منقضی می‌شوند و پس از مدت زمانی از پیش تعیین‌شده از فروشگاه روی دستگاه حذف می‌شوند. مقدار پیش فرض باید تعیین شود. مالک می تواند این مقدار پیش فرض را لغو کند.

کنترل کاربر

• این پیشنهاد قصد دارد به کاربران امکان مشاهده لیست برنامه های نصب شده را بدهد که حداقل یک مخاطب سفارشی ایجاد کرده اند
• کاربران می توانند برنامه ها را از این لیست حذف کنند. حذف تمام مخاطبان سفارشی مرتبط با برنامه ها را پاک می کند و از پیوستن برنامه ها به مخاطبان سفارشی جدید جلوگیری می کند.
• کاربران این امکان را دارند که API مخاطب محافظت شده را به طور کامل بازنشانی کنند. وقتی این اتفاق می‌افتد، همه مخاطبان سفارشی موجود در دستگاه پاک می‌شوند.
• کاربران این امکان را دارند که به طور کامل از Privacy Sandbox در Android که شامل Protected Audience API است، انصراف دهند. اگر کاربر از جعبه ایمنی حریم خصوصی انصراف داده باشد، API مخاطب محافظت شده بی‌صدا از کار می‌افتد.

طراحی این قابلیت در حال انجام است و جزئیات آن در آپدیت بعدی درج خواهد شد.

به روز رسانی های برنامه ریزی شده

راه‌حل‌هایی که قبلاً توضیح داده شد، به برنامه یا SDK فناوری تبلیغات نیاز دارند تا زمانی که برنامه در پیش‌زمینه است، APIها را فراخوانی کند و ویژگی‌های کامل مخاطبان سفارشی را مستقیماً یا با استفاده از تفویض اختیار ارائه کند. با این حال، همیشه برای تبلیغ‌کنندگان و ارائه‌دهندگان فناوری تبلیغات امکان‌پذیر نیست که در زمان استفاده از برنامه، کاربر به کدام مخاطبان تعلق دارد.

برای تسهیل این امر، این امکان برای فناوری تبلیغات وجود دارد که API scheduleCustomAudienceUpdate() فراخوانی کند. این API به تماس‌گیرنده اجازه می‌دهد تا زمانی را که باید تماس API برقرار شود، تعیین کند، بنابراین زمان بیشتری را برای فناوری آگهی پاسخ‌دهنده فراهم می‌کند تا رویدادهای سطح برنامه را پردازش کند و تعیین کند کاربر باید به کدام مخاطبان محافظت‌شده ملحق شود یا از آنها حذف شود.

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

ScheduleCustomAudienceUpdateRequest

public final class ScheduleCustomAudienceUpdateRequest {
  // Required Field
  @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

  // Required Field
  @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

  //  Required Field
  @NonNull public List<PartialCustomAudience> getPartialCustomAudienceList() {
    return mPartialCustomAudiences;
  }

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

ScheduleCustomAudienceUpdateRequest حاوی اطلاعات لازم برای ثبت یک کار تاخیری برای اجرا با پلتفرم است. پس از تأخیر مشخص شده، یک کار پس زمینه به صورت دوره ای اجرا می شود و درخواست (ها) را ارسال می کند. ScheduleCustomAudienceUpdateRequest می تواند حاوی اطلاعات زیر باشد:

• UpdateUri : نقطه پایانی URI که یک تماس GET برای دریافت به‌روزرسانی ارسال می‌شود. هویت خریدار ذاتاً از eTLD+1 استنباط می‌شود و نیازی به ارائه صریح نیست و با پاسخ به‌روزرسانی نمی‌توان آن را تغییر داد. درخواست GET انتظار دارد یک شی JSON حاوی لیستی از اشیاء customAudience در ازای آن باشد.
• DelayTime : زمان نشان دهنده تأخیر از زمان برقراری فراخوانی API scheduleCustomAudienceUpdate() برای برنامه ریزی به روز رسانی است.

• PartialCustomAudience : API همچنین به SDK روی دستگاه اجازه می دهد تا لیستی از مخاطبان سفارشی ساخته شده را ارسال کند. این به SDK های درون برنامه ای اجازه می دهد تا نقش دوگانه را ایفا کنند، از کنترل کامل تا جزئی بر مدیریت مخاطبان سفارشی بر اساس مشارکت آنها با DSP.

  • این همچنین این API را با API fetchAndJoinCustomAudience() که امکان به اشتراک گذاری اطلاعات مشابه را فراهم می کند، سازگار نگه می دارد.

• ShouldReplacePendingUpdates : Boolean که تعیین می کند آیا هر به روز رسانی برنامه ریزی شده معلق باید لغو شود و با به روز رسانی که در ScheduleCustomAudienceUpdateRequest فعلی توضیح داده شده است جایگزین شود. اگر این مقدار روی false تنظیم شود و به‌روزرسانی‌های درخواستی قبلی همچنان برای همان خریدار در همان برنامه در حال تعلیق باشد، تماس با scheduleCustomAudienceUpdate با این ScheduleCustomAudienceUpdateRequest ناموفق خواهد بود. پیش فرض ها به false .

مجوزها و کنترل برنامه

این پیشنهاد قصد دارد کنترل برنامه ها را بر روی مخاطبان سفارشی خود ارائه دهد:

• یک برنامه می تواند ارتباط خود را با مخاطبان سفارشی مدیریت کند.
• یک برنامه می‌تواند به پلتفرم‌های فناوری تبلیغات شخص ثالث اجازه دهد تا مخاطبان سفارشی را از طرف خود مدیریت کند.

طراحی این قابلیت در حال انجام است و جزئیات آن در آپدیت بعدی درج خواهد شد.

کنترل پلت فرم فناوری تبلیغات

این پیشنهاد راه‌هایی را برای فناوری‌های تبلیغاتی برای کنترل مخاطبان سفارشی خود بیان می‌کند:

• متخصصان تبلیغات در جعبه ایمنی حریم خصوصی ثبت‌نام می‌کنند و یک دامنه eTLD+1 ارائه می‌کنند که با همه URL‌های یک مخاطب سفارشی مطابقت دارد.
• فناوری‌های تبلیغاتی می‌توانند با برنامه‌ها یا SDK همکاری کنند تا نشانه‌های تأییدی را ارائه کنند که برای تأیید ایجاد مخاطب سفارشی استفاده می‌شود. وقتی این فرآیند به یک شریک واگذار می‌شود، ایجاد مخاطب سفارشی می‌تواند به گونه‌ای پیکربندی شود که نیاز به تأیید توسط فناوری تبلیغات داشته باشد.
• یک فناوری تبلیغاتی می‌تواند از طرف خود تماس‌های joinCustomAudience غیرفعال کند و فقط به fetchAndJoinCustomAudience API اجازه دهد تا همه مخاطبان سفارشی تماس را فعال کند. کنترل را می توان در حین ثبت نام در جعبه ایمنی حریم خصوصی به روز کرد. توجه داشته باشید که کنترل به همه فناوری های تبلیغاتی اجازه می دهد یا هیچ کدام. به دلیل محدودیت‌های پلتفرم، مجوزهای تفویض اختیار نمی‌تواند بر اساس فناوری تبلیغاتی باشد.

تبلیغات نامزد و پاسخ ابرداده

تبلیغات و ابرداده کاندیدای بازگردانده شده از یک پلت فرم سمت خرید باید شامل فیلدهای زیر باشد:

• فراداده: فراداده تبلیغاتی مربوط به سمت خرید، مخصوص تبلیغات. به عنوان مثال، این ممکن است شامل اطلاعاتی در مورد کمپین تبلیغاتی و معیارهای هدف مانند مکان و زبان باشد.
• Render URL: نقطه پایانی برای ارائه خلاقانه آگهی.
• فیلتر: اطلاعات اختیاری لازم برای API مخاطب محافظت شده برای فیلتر کردن تبلیغات بر اساس داده‌های موجود در دستگاه. برای جزئیات بیشتر، بخش خرید منطق فیلتر جانبی را بخوانید.

گردش کار انتخاب آگهی

هدف این پیشنهاد بهبود حریم خصوصی با معرفی Ad Selection API است که اجرای حراج برای پلتفرم‌های فناوری تبلیغات را تنظیم می‌کند.

پلتفرم‌های فناوری تبلیغات امروزه معمولاً مناقصه و انتخاب آگهی را منحصراً بر روی سرورهای خود انجام می‌دهند. با این پیشنهاد، مخاطبان سفارشی و سایر سیگنال های حساس کاربر، مانند اطلاعات بسته نصب شده موجود، تنها از طریق Ad Selection API قابل دسترسی خواهند بود. علاوه بر این، برای موارد استفاده از بازاریابی مجدد، تبلیغات نامزد خارج از باند (یعنی نه در زمینه ای که تبلیغات در آن نشان داده می شود) واکشی می شود. پلتفرم‌های فناوری تبلیغات باید آماده شوند تا برخی از بخش‌های منطق حراج فعلی و انتخاب آگهی خود را روی دستگاه اجرا و اجرا کنند. پلتفرم های فناوری تبلیغات ممکن است تغییرات زیر را در گردش کار انتخاب آگهی خود در نظر بگیرند:

• بدون اطلاعات بسته نصب شده موجود در سرور، پلتفرم‌های فناوری تبلیغات ممکن است بخواهند چندین آگهی متنی را به دستگاه ارسال کنند و گردش کار انتخاب آگهی را فراخوانی کنند تا فیلتر مبتنی بر نصب برنامه فعال شود تا شانس نمایش یک آگهی مرتبط را به حداکثر برسانند.
• از آنجایی که تبلیغات بازاریابی مجدد از باند خارج می‌شوند، مدل‌های پیشنهادی فعلی ممکن است نیاز به به‌روزرسانی داشته باشند. پلتفرم‌های فناوری تبلیغات ممکن است بخواهند مدل‌های فرعی مناقصه ایجاد کنند (پیاده‌سازی ممکن است بر اساس الگویی به نام مدل دو برج باشد) که می‌تواند روی ویژگی‌های تبلیغات و سیگنال‌های زمینه‌ای به طور جداگانه کار کند و خروجی‌های مدل فرعی روی دستگاه را برای پیش‌بینی قیمت‌ها ترکیب کند. این می تواند هم از مزایده های سمت سرور و هم از مزایده ها برای هر فرصت تبلیغاتی استفاده کند.

این رویکرد داده‌های تعامل برنامه کاربر را قادر می‌سازد تا انتخاب آگهی‌ها را مطلع کند، در حالی که اشتراک‌گذاری این داده‌ها با اشخاص ثالث را محدود می‌کند.

این گردش کار انتخاب آگهی، اجرای کد جاوا اسکریپت ارائه شده توسط فناوری تبلیغات را بر روی دستگاه بر اساس دنباله زیر هماهنگ می کند:

1. اجرای منطق مناقصه سمت خرید
2. فیلتر و پردازش آگهی سمت خرید
3. اجرای منطق تصمیم گیری سمت فروش

برای انتخاب‌های تبلیغاتی که شامل مخاطبان سفارشی می‌شود، پلتفرم کد جاوا اسکریپت ارائه‌شده جانبی خرید را بر اساس نقطه پایانی URL عمومی تعریف‌شده توسط فراداده «Bidding Logic URL» مخاطبان سفارشی دریافت می‌کند. نقطه پایانی URL برای کد تصمیم گیری سمت فروش نیز به عنوان ورودی برای شروع گردش کار انتخاب آگهی ارسال می شود.

طراحی تبلیغات انتخابی که شامل مخاطبان سفارشی نمی شود در حال طراحی فعال است.

گردش کار انتخاب آگهی را آغاز کنید

هنگامی که یک برنامه نیاز به نمایش آگهی دارد، SDK پلت فرم فناوری تبلیغات ممکن است با فراخوانی متد selectAds() گردش کار انتخاب آگهی را پس از نمونه سازی شی AdSelectionConfig با پارامترهای مورد انتظار آغاز کند:

• فروشنده : شناسه پلتفرم تبلیغات سمت فروش، به دنبال قالب eTLD+1
• URL منطقی تصمیم گیری : هنگامی که یک مزایده تبلیغاتی شروع می شود، پلتفرم از این نشانی اینترنتی برای واکشی کد جاوا اسکریپت از پلت فرم سمت فروش استفاده می کند تا یک تبلیغ برنده را به دست آورد.
• خریداران مخاطب سفارشی : فهرستی از پلتفرم‌های سمت خرید با تقاضای سفارشی مبتنی بر مخاطب برای این حراج، به دنبال قالب eTLD+1.
• سیگنال های انتخاب آگهی : اطلاعات مربوط به حراج (اندازه آگهی، قالب آگهی و غیره).
• سیگنال های فروشنده : سیگنال های خاص پلت فرم جانبی را تامین کنید.
• نشانی اینترنتی سیگنال‌های امتیازدهی معتمد : نقطه پایانی نشانی اینترنتی سیگنال قابل اعتماد طرف فروش که می‌توان اطلاعات خلاقانه خاص را از آن دریافت کرد.
• سیگنال‌های هر خریدار : طرف‌های تقاضای شرکت‌کننده ممکن است از این پارامتر برای ارائه ورودی‌های حراج استفاده کنند. به عنوان مثال، این پارامتر ممکن است شامل اطلاعات متنی جامعی باشد که برای تعیین پیشنهادها مفید است.

قطعه کد تصویری زیر یک SDK پلت فرم فناوری تبلیغات را نشان می دهد که گردش کار انتخاب آگهی را با تعریف AdSelectionConfig و سپس فراخوانی selectAds برای دریافت آگهی برنده آغاز می کند:

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

منطق مناقصه سمت خرید

منطق مناقصه معمولاً توسط پلتفرم های سمت خرید ارائه می شود. هدف این کد تعیین قیمت پیشنهادی برای تبلیغات نامزد است. ممکن است منطق تجاری اضافی را برای تعیین نتیجه اعمال کند.

این پلتفرم از فراداده مخاطبان سفارشی "Bidding logic URL" برای واکشی کد جاوا اسکریپت که باید شامل امضای تابع زیر باشد استفاده خواهد کرد:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

متد generateBid() مبلغ پیشنهادی محاسبه شده را برمی گرداند. پلتفرم این تابع را برای همه تبلیغات (متنفی یا بازاریابی مجدد) به صورت متوالی فراخوانی می کند. اگر چندین ارائه دهنده منطق مناقصه وجود داشته باشد، سیستم توالی اجرا را در بین ارائه دهندگان تضمین نمی کند.

تابع انتظار پارامترهای زیر را دارد:

• آگهی : آگهی در نظر گرفته شده توسط کد مناقصه سمت خرید. این آگهی از یک مخاطب سفارشی واجد شرایط خواهد بود
• سیگنال های حراج : سیگنال های سمت فروش، سیگنال های مخصوص پلت فرم.
• سیگنال‌های هر خریدار : طرف‌های تقاضای شرکت‌کننده ممکن است از این پارامتر برای ارائه ورودی‌های حراج استفاده کنند. به عنوان مثال، این پارامتر ممکن است شامل اطلاعات متنی جامعی باشد که برای تعیین پیشنهادها مفید است.
• سیگنال‌های مناقصه قابل اعتماد : پلتفرم‌های فناوری تبلیغات برای اطلاع‌رسانی به بازیابی و امتیازدهی آگهی به داده‌های زمان واقعی متکی هستند. به عنوان مثال، ممکن است بودجه یک کمپین تبلیغاتی تمام شود و باید فوراً ارائه آن متوقف شود. یک Ad-tech می‌تواند یک نقطه پایانی URL را از جایی که این داده‌های بی‌درنگ واکشی می‌شود و مجموعه کلیدهایی که باید جستجوی بی‌درنگ برای آن‌ها انجام شود، تعریف کند. سرور مدیریت شده پلت فرم فناوری تبلیغات که این درخواست را ارائه می دهد، یک سرور قابل اعتماد خواهد بود که توسط پلت فرم فناوری تبلیغات مدیریت می شود.
• سیگنال‌های متنی : این ممکن است شامل مُهر زمانی درشت یا اطلاعات موقعیت مکانی تقریبی یا هزینه هر کلیک روی آگهی باشد.
• سیگنال های کاربر : ممکن است شامل اطلاعاتی مانند اطلاعات بسته نصب شده موجود باشد.

هزینه تبلیغات

علاوه بر پیشنهاد، پلتفرم های سمت خرید این گزینه را دارند که هزینه هر کلیک را به عنوان بخشی از generateBid() برگردانند. به عنوان مثال:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

اگر این تبلیغ برنده باشد، adCost به صورت تصادفی به 8 بیت برای حفظ حریم خصوصی گرد می شود. سپس مقدار گرد شده adCost به پارامتر contextual_signals در reportWin در حین گزارش‌گیری ارسال می‌شود.

منطق فیلتر طرف خرید

پلتفرم‌های سمت خرید می‌توانند تبلیغات را بر اساس سیگنال‌های اضافی موجود در دستگاه در مرحله انتخاب آگهی فیلتر کنند. به عنوان مثال، پلتفرم‌های فناوری تبلیغات می‌توانند قابلیت‌های محدود کردن فرکانس را در اینجا پیاده‌سازی کنند. اگر چندین ارائه دهنده فیلتر وجود داشته باشد، سیستم توالی اجرا را در بین ارائه دهندگان تضمین نمی کند.

منطق فیلتر سمت خرید را می توان به عنوان بخشی از منطق مناقصه با بازگرداندن ارزش پیشنهادی 0 برای یک تبلیغ معین پیاده سازی کرد.

علاوه بر آن، پلتفرم‌های سمت خرید می‌توانند نشان دهند که یک آگهی خاص باید براساس سیگنال‌های اضافی روی دستگاه در دسترس مخاطبان محافظت‌شده فیلتر شود و از دستگاه خارج نمی‌شود. همانطور که ما طرح‌های منطق فیلتر اضافی را تثبیت می‌کنیم، پلتفرم‌های سمت خرید از همین ساختار پیروی می‌کنند تا نشان دهند که فیلتر باید اتفاق بیفتد.

منطق امتیازدهی طرف فروش

منطق امتیازدهی معمولاً توسط پلت فرم سمت فروش ارائه می شود. هدف کد تعیین یک تبلیغ برنده بر اساس خروجی های منطقی مناقصه است. ممکن است منطق تجاری اضافی را برای تعیین نتیجه اعمال کند. اگر چندین ارائه دهنده منطق تصمیم وجود داشته باشد، سیستم توالی اجرا را در بین ارائه دهندگان تضمین نمی کند. پلتفرم از پارامتر ورودی "Decision Logic URL" API selectAds() برای واکشی کد جاوا اسکریپت که باید شامل امضای تابع زیر باشد استفاده خواهد کرد:

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

تابع انتظار پارامترهای زیر را دارد:

• آگهی : آگهی در حال ارزیابی خروجی از تابع generateBid()
• Bid : مقدار پیشنهاد خروجی از تابع generateBid() .
• Auction config : پارامتر ورودی به متد selectAds() .
• سیگنال‌های امتیازدهی مورد اعتماد : پلت‌فرم‌های فناوری تبلیغات برای اطلاع‌رسانی فیلترینگ و امتیازدهی تبلیغات به داده‌های بی‌درنگ متکی هستند. به عنوان مثال، یک ناشر برنامه ممکن است یک کمپین تبلیغاتی را از نمایش تبلیغات در برنامه مسدود کند. این داده ها از پارامتر نشانی وب سیگنال های امتیازدهی مطمئن پیکربندی حراج واکشی شده است. سروری که این درخواست را ارائه می‌کند باید یک سرور مورد اعتماد با فناوری تبلیغاتی باشد.
• سیگنال متنی : ممکن است شامل اطلاعات مُهر زمانی درشت یا تقریبی باشد.
• سیگنال کاربر : ممکن است شامل اطلاعاتی مانند فروشگاه برنامه باشد که نصب برنامه را آغاز کرده است.
• سیگنال مخاطب سفارشی : اگر تبلیغی که امتیاز می‌گیرد از یک مخاطب سفارشی روی دستگاه باشد، حاوی اطلاعاتی مانند خواننده و نام مخاطب سفارشی است.

زمان اجرای کد انتخاب آگهی

در این پیشنهاد، سیستم کد حراج ارائه شده توسط پلتفرم فناوری تبلیغات را از نقاط پایانی URL قابل تنظیم دریافت کرده و در دستگاه اجرا خواهد کرد. با توجه به محدودیت های منابع در دستگاه های تلفن همراه، کد حراج باید از دستورالعمل های زیر پیروی کند:

• اجرای کد باید در مدت زمان از پیش تعریف شده به پایان برسد. این محدودیت به طور یکسان برای همه شبکه های تبلیغاتی خریدار اعمال می شود. جزئیات این محدودیت در به روز رسانی بعدی به اشتراک گذاشته خواهد شد.
• کد باید مستقل باشد و وابستگی خارجی نداشته باشد.

از آنجایی که کد حراج، مانند منطق مناقصه ممکن است نیاز به دسترسی به داده های کاربر خصوصی مانند منابع نصب برنامه داشته باشد، زمان اجرا دسترسی به شبکه یا ذخیره سازی را فراهم نمی کند.

زبان برنامه نویسی

کد حراج ارائه شده توسط پلت فرم فناوری تبلیغاتی باید با جاوا اسکریپت نوشته شود. این به پلتفرم‌های فناوری تبلیغات اجازه می‌دهد، برای مثال، کد پیشنهادی را در پلتفرم‌هایی که از جعبه ایمنی حریم خصوصی پشتیبانی می‌کنند، به اشتراک بگذارند.

رندر آگهی برنده

آگهی با بالاترین امتیاز برنده مزایده محسوب می شود. در این پیشنهاد اولیه، تبلیغ برنده برای رندر به SDK منتقل می شود.

این طرح توسعه راه حلی است تا اطمینان حاصل شود که اطلاعات مربوط به عضویت مخاطب سفارشی کاربر، یا سابقه تعامل برنامه، توسط برنامه یا SDK از طریق اطلاعات مربوط به آگهی برنده (مشابه پیشنهاد قاب‌های حصاردار Chrome) قابل تعیین نیست.

برداشت و گزارش رویداد

پس از رندر شدن تبلیغ، می توان برداشت برنده را به پلتفرم های طرف خرید و فروش شرکت کننده گزارش داد. این به خریداران و فروشندگان این امکان را می دهد که اطلاعات مربوط به حراج، مانند پیشنهاد یا نام مخاطبان سفارشی را با گزارش برداشت برنده درج کنند. علاوه بر این، پلتفرم سمت فروش و سمت خرید برنده واجد شرایط دریافت گزارش‌های اضافی در سطح رویداد درباره آگهی برنده هستند. این امکان را فراهم می کند که اطلاعات مربوط به حراج (پیشنهاد، نام مخاطبان سفارشی و غیره) را با کلیک ها، بازدیدها و سایر رویدادهای تبلیغاتی شامل شود. پلتفرم منطق گزارش دهی را به این ترتیب فرا می خواند:

1. گزارش سمت فروش
2. گزارش سمت خرید

این به پلتفرم‌های سمت خرید و فروش راهی برای ارسال اطلاعات مهم روی دستگاه به سرورها می‌دهد تا قابلیت‌هایی مانند بودجه‌بندی زمان واقعی، به‌روزرسانی‌های مدل پیشنهادی، و گردش‌های کاری دقیق صورت‌حساب را فعال کنند. این پشتیبانی از گزارش برداشت مکمل API گزارش Attribution است.

دو مرحله برای پشتیبانی از گزارش رویداد مورد نیاز است: جاوا اسکریپت سمت فروش و سمت خرید باید ثبت کند که برای چه رویدادی باید گزارش رویداد را دریافت کند، و طرف فروش مسئول گزارش اطلاعات در سطح رویداد است.

مخاطبان محافظت شده مکانیسمی را برای عضویت در رویدادهای آینده مربوط به حراج برنده با ثبت نام چراغها فراهم می کنند. در عملکرد reportResult() javaScript یک فروشنده ، سیستم عامل های طرف فروش می توانند چراغ ها را با استفاده از عملکرد ثبت نام Platform's registerAdBeacon() ثبت کنند. به طور مشابه ، سیستم عامل های سمت خرید می توانند از عملکرد registerAdBeacon() از عملکرد reportWin() JavaScript خود تماس بگیرند.

registerAdBeacon(beacons)

ورودی:

• event_key : رشته ای که نشان می دهد کدام نوع تعامل برای ثبت نام است. این به عنوان یک کلید برای جستجوی نقطه پایانی پلتفرم در هنگام گزارش نتایج حراج استفاده می شود.
• reporting_url : URL متعلق به پلت فرم AD Tech برای رسیدگی به این رویداد.

کلیدهای رویداد شناسه های رشته ای هستند که متعلق به SDK طرف فروش هستند که مسئول گزارش نتایج حراج هستند. برای ایجاد پاسخ به تماس ، Techs Ad Beacons را با کلیدهایی که با کلیدهای استفاده شده توسط طرف فروش هنگام گزارش وقایع مطابقت دارند ، ثبت می کنند. اینها نیازی به ناشناس بودن ندارند ، اگرچه محدودیت هایی برای کمیت و طول کلیدها وجود دارد که می توانند برای مخاطبان سفارشی خاص ثبت شوند. در صورت فراخوانی reportEvent() ، سیستم عامل های سمت فروش که حراج را اجرا می کنند ، همیشه واجد شرایط دریافت این گزارش های رویداد هستند. فقط پلت فرم برنده خرید واجد شرایط دریافت این گزارش ها است.

گزارش سمت فروش

این پلتفرم عملکرد reportResult() javaScript را در کد جانبی ارائه شده بارگیری شده از پارامتر URL منطق تصمیم فروشنده برای selectAds() API فراخوانی می کند: API:

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

خروجی: یک شی json حاوی

• وضعیت: 0 برای موفقیت ، هر مقدار دیگر برای شکست.
• URL Reporting: این پلتفرم از این URL برگشته شده از عملکرد فراخوانی می کند.
• سیگنال های خریدار: یک شیء JSON که باید به عملکرد reportWin خریدار منتقل شود.

طرف عرضه ممکن است سیگنال های مربوطه را در URL گزارش دهی رمزگذاری کند تا به آنها کمک کند تا بینش بیشتری در مورد حراج و آگهی برنده کسب کنند. به عنوان مثال ، ممکن است سیگنال های زیر را شامل شود:

• آدرس تبلیغاتی تبلیغاتی
• مبلغ پیشنهاد برنده
• نام برنامه
• شناسه های پرس و جو
• سیگنال های خریدار: برای پشتیبانی از به اشتراک گذاری داده ها بین سمت عرضه و طرف تقاضا ، این پلتفرم به عنوان یک پارامتر ورودی برای تقاضای کد گزارش ، این مقدار بازده را منتقل می کند.

گزارش سمت خرید

این پلتفرم از عملکرد reportWin() JavaScript در کد جانبی تقاضا که از ابرداده URL منطق مناقصه بارگیری شده از مخاطبان سفارشی مرتبط با حراج استفاده می شود ، فراخوانی می کند.

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

ورودی:

• auction_signals و per_buyer_signals از AuctionConfig خارج می شوند. هرگونه اطلاعاتی که باید پلت فرم خرید برای ورود به URL گزارش دهی از این داده باشد.
• signals_for_buyer خروجی Reportresult طرف فروش است. این امر فرصتی را برای به اشتراک گذاشتن داده ها با بستر خرید برای اهداف گزارش فراهم می کند.
• contextual_signals شامل اطلاعاتی مانند نام برنامه و custom_audience_signals شامل اطلاعات مخاطبان سفارشی است. اطلاعات دیگر ممکن است در آینده اضافه شود.

خروجی:

• وضعیت: 0 برای موفقیت ، هر مقدار دیگر برای شکست.
• URL Reporting: این پلتفرم از این URL برگشته شده از عملکرد فراخوانی می کند.

گزارش وقایع

گزارش های گزارش فقط پس از اتمام گزارش برای حراج امکان پذیر است. SDK سمت فروش وظیفه گزارش هرگونه رویداد را بر عهده دارد. این پلتفرم یک API را در معرض نمایشگاه ReportEventRequest قرار می دهد که حراج اخیراً اجرا شده ، کلید رویداد را که گزارش شده است ، داده های مرتبط با آن کلید ، چه گزارش باید به خریدار یا فروشنده (یا هر دو) ارسال شود و یک رویداد ورودی اختیاری برای رویدادهای تبلیغاتی را در اختیار شما قرار می دهد. مشتری کلید رویداد و جمع آوری داده ها را برای گزارش تعریف می کند.

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

ورودی:

• ad_selection_id باید یک AdSelectionId از حراج اخیراً اجرا شده از AdSelectionOutcome باشد.
• event_key یک رشته تعریف شده از طرف فروش است که رویداد تعامل را توصیف می کند.
• event_data رشته ای است که داده های مرتبط با event_key را نشان می دهد
• reporting_destinations یک مجموعه ماسک کمی با استفاده از پرچم های ارائه شده توسط سیستم عامل است. این می تواند یکی از FLAG_REPORTING_DESTINATION_SELLER یا FLAG_REPORTING_DESTINATION_BUYER یا هر دو باشد.
• input_event (اختیاری) برای ادغام با API گزارش انتساب استفاده می شود. این یا یک شیء InputEvent (برای یک رویداد کلیک) یا NULL (برای یک رویداد مشاهده) است. برای اطلاعات بیشتر در مورد این پارامتر ، به ادغام API گزارش Attribution مراجعه کنید.

پس از فروش SDK از reportEvent و بسته به پرچم reporting_destinations ، این پلتفرم تلاش می کند تا با کلیدهای ثبت شده توسط خریداران و فروشندگان در کارکردهای reportWin و reportResult JavaScript event_key داشته باشد. اگر یک مسابقه وجود داشته باشد ، پلتفرم event_data به reporting_url مرتبط_ورل ارسال می کند. نوع محتوای درخواست متن ساده است که بدن آن event_data است. این درخواست به عنوان بهترین تلاش انجام می شود و در صورت بروز خطای شبکه ، پاسخ به خطای سرور یا در صورت یافتن کلیدهای تطبیق ، سکوت می شود.

انتساب گزارش API یکپارچه سازی

برای حمایت از خریدارانی که در حراج مخاطبان محافظت شده شرکت می کنند ، ما در حال ارائه قابلیت های متقابل API در بین مخاطبان محافظت شده و API های گزارشگر (ARA) هستیم. این عملکرد ، فناوری های تبلیغاتی را قادر می سازد تا عملکرد انتساب خود را در تاکتیک های مختلف بازاریابی ارزیابی کنند ، تا بتوانند درک کنند که کدام نوع مخاطبان بالاترین ROI را ارائه می دهند.

از طریق این ادغام متقابل API ، AdTechs می تواند:

• یک نقشه با ارزش کلیدی URIS ایجاد کنید تا برای هر دو) 1) گزارش تعامل AD و 2) ثبت نام منبع استفاده شود.
• داده های حراج را از حراج مخاطبان محافظت شده در نقشه برداری کلید سمت منبع خود برای گزارش خلاصه کل (با استفاده از API گزارش انتساب) برای اطلاعات بیشتر به پیشنهاد طراحی ARA مراجعه کنید.

وقتی کاربر روی یک تبلیغ می بیند یا کلیک می کند:

• URL مورد استفاده برای گزارش تعامل آن رویدادها با استفاده از مخاطبان محافظت شده ، داده های لازم را برای خریدار فراهم می کند تا برای ثبت یک نمای یا کلیک به عنوان یک منبع واجد شرایط با API گزارشگری Attribution استفاده شود.
• AD Tech ممکن است با استفاده از آن URL ، تصویب CustomAudience (یا سایر اطلاعات متنی مربوطه در مورد تبلیغ مانند قرار دادن تبلیغ یا مدت زمان مشاهده) را انتخاب کند تا این ابرداده بتواند هنگام بررسی عملکرد کمپین ، به گزارش های خلاصه انتشار دهد.

ثبت نام منبع

reportEvent() یک پارامتر اختیاری جدید InputEvent می پذیرد. خریداران برنده که چراغهای تبلیغاتی را ثبت می کنند می توانند انتخاب کنند که گزارش های گزارش گزارش شده در API های گزارش انتساب به عنوان یک منبع ثبت شده ثبت می شوند. درخواست Aptribution-Report-Reportile به کلیه درخواست های گزارش رویداد ارسال شده از reportEvent() اضافه می شود. هرگونه پاسخ با هدرهای مناسب ARA به همان روشی که پاسخ ثبت نام منبع ARA معمولی دیگر تجزیه می شود ، تجزیه می شود. برای نحوه ثبت URL منبع ، به API توضیح دهنده گزارش انتساب مراجعه کنید.

از آنجا که ARA در Android از مشاهده و رویدادهای کلیک پشتیبانی می کند ، InputEvents برای تمایز بین این دو نوع استفاده می شود. دقیقاً مانند ثبت نام منبع ARA ، API reportEvent() یک InputEvent با تأیید شده از پلتفرم را به عنوان یک رویداد کلیک تفسیر می کند. اگر InputEvent از دست رفته ، تهی یا نامعتبر باشد ، ثبت نام منبع یک دیدگاه در نظر گرفته می شود.

توجه داشته باشید که eventData پس از حراج ممکن است حاوی اطلاعات حساس باشد ، بنابراین این پلتفرم eventData را در درخواست های ثبت نام منبع هدایت می کند.

نامزدی و گزارش تبدیل به عنوان مثال

در این مثال ، ما از دیدگاه خریدار که علاقه مند به ارتباط داده های حراج ، تبلیغات تبلیغاتی و برنامه تبدیل با هم هستیم ، به آن نگاه خواهیم کرد.

در این گردش کار ، خریدار با فروشنده هماهنگی می کند تا یک شناسه منحصر به فرد را به حراج بفرستد. در حراج ، خریدار این شناسه منحصر به فرد را با داده های حراج ارسال می کند. در طول زمان رندر و تبدیل ، داده های آگهی ارائه شده نیز با همان شناسه منحصر به فرد ارسال می شود. بعداً ، از شناسه منحصر به فرد می توان برای ارتباط این گزارش ها استفاده کرد.

گردش کار: قبل از شروع حراج ، خریدار شناسه منحصر به فرد را به عنوان بخشی از پاسخ پیشنهادات برنامه نویسی زمان واقعی ("RTB") به فروشنده ارسال می کند. شناسه را می توان به عنوان متغیر مانند auctionId تنظیم کرد. این شناسه به عنوان perBuyerSignals در auctionConfig منتقل می شود و در منطق مناقصه خریدار در دسترس قرار می گیرد.

1. در حین اجرای reportWin ، خریدار می تواند یک چراغ تبلیغاتی را ثبت کند که در طول زمان ارائه تبلیغات و برای وقایع خاص تعامل ایجاد شود ( registerAdBeacon() ). برای مرتبط کردن سیگنال های حراج برای یک رویداد تبلیغاتی ، auctionId را به عنوان یک پرس و جو از URL Beacon تنظیم کنید.
2. در طول زمان ارائه آگهی ، چراغهایی که در طول زمان حراج ثبت کرده اید می تواند با داده های سطح رویداد شروع یا تقویت شود. فروشنده باید reportEvent() تحریک کند و در داده های سطح رویداد عبور کند. این پلتفرم URL AD Beacon Ad ثبت شده خریدار را که با reportEvent() ایجاد شده ارتباط دارد ، پینگ می کند.
3. خریدار با پاسخ دادن به درخواست های Beacon Ad با عنوان Attribution-Reporting-Register-Source تبلیغات را در API گزارش انتساب ثبت می کند. برای مرتبط کردن سیگنال های حراج برای یک رویداد تبدیل ، auctionId در URL منبع ثبت نام تنظیم کنید.

پس از روند فوق ، خریدار گزارش حراج ، گزارش تعامل و گزارش تبدیل را خواهد داشت که می تواند با استفاده از شناسه منحصر به فرد که می تواند برای ارتباط با یکدیگر استفاده شود ، با هم ارتباط داشته باشد.

گردش کار مشابه در صورت نیاز به دسترسی به داده های انتساب در مورد فروشنده اعمال می شود و فروشنده همچنین می تواند از یک شناسه منحصر به فرد برای ارسال با registerAdBeacon() استفاده کند. تماس reportEvent() شامل یک ویژگی مقصد است که می تواند برای ارسال گزارش به خریدار و فروشنده استفاده شود.

پلت فرم فناوری تبلیغاتی سرور قابل اعتماد را مدیریت کرد

منطق انتخاب آگهی امروز به اطلاعات در زمان واقعی مانند وضعیت کاهش بودجه نیاز دارد تا مشخص شود که آیا داوطلبان تبلیغات باید برای حراج انتخاب شوند. هر دو سیستم عامل خرید و طرف فروش قادر به دریافت این اطلاعات از سرورهایی هستند که آنها کار می کنند. به منظور به حداقل رساندن نشت هرگونه اطلاعات حساس از طریق این سرورها ، این پیشنهاد خواستار محدودیت های زیر است:

• رفتارهای این سرورها ، که بعداً در این بخش شرح داده شده است ، اطلاعات کاربر را نشت نمی کند.
• سرورها بر اساس داده هایی که می بینند ، پروفایل های مستعار ایجاد نمی کنند ، یعنی باید به آنها اعتماد شود.

طرف خرید : پس از خرید سمت ، منطق مناقصه خرید سمت خرید را آغاز می کند ، این پلتفرم یک HTTP از داده های مناقصه قابل اعتماد از سرور قابل اعتماد انجام می دهد. URL با افزودن URL و کلیدهای موجود در سیگنال های پیشنهادی قابل اعتماد ابرداده از مخاطبان سفارشی که پردازش می شوند ، تشکیل شده است. این واکشی فقط در هنگام پردازش تبلیغات از مخاطبان سفارشی دستگاه انجام می شود. در این مرحله ، طرف خرید می تواند بودجه ها را اجرا کند ، مکث کمپین / حالت Unpause ، انجام هدف قرار دادن و غیره را بررسی کند.

در زیر یک URL نمونه برای واکشی داده های پیشنهادی قابل اعتماد ، بر اساس ابرداده سیگنال مناقصه قابل اعتماد از مخاطبان سفارشی آورده شده است:

https://www.kv-server.example/getvalues?keys=key1,key2

پاسخ سرور باید یک شیء JSON باشد که کلیدهای آن Key1 ، Key2 و غیره است و مقادیر آن در دسترس توابع مناقصه خریدار قرار می گیرد.

Sell ​​Side : مشابه با جریان سمت خرید در بالا ، Sell Side ممکن است بخواهد اطلاعات مربوط به خلاقین را که در حراج در نظر گرفته شده است ، بدست آورد. به عنوان مثال ، یک ناشر ممکن است بخواهد که بر اساس نگرانی های ایمنی برند در برنامه خود در برنامه خود نشان داده نشده باشد. این اطلاعات را می توان دریافت کرد و در دسترس منطق حراج سمت فروش قرار داد. شبیه به جستجوی سرور قابل اعتماد سمت خرید ، فروش سرور قابل اعتماد طرف را نیز با استفاده از HTTP Fetch اتفاق می افتد. URL با افزودن URL سیگنال های امتیاز دهی قابل اعتماد با URL های ارائه شده از خلاقیت هایی که داده ها نیاز به آن دارند ، تشکیل شده است.

در زیر یک URL نمونه برای واکشی اطلاعات مربوط به خلاقین در حراج ، بر اساس URL های ارائه خلاق:

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

پاسخ سرور باید یک شیء JSON باشد که کلیدهای آن URL های ارسال شده در درخواست ارسال شده است.

این سرورها به روشی قابل اعتماد برای ارائه چندین مزایای امنیتی و حریم خصوصی فعالیت می کنند:

• به مقدار بازگشت سرور برای هر کلید می توان اعتماد کرد که فقط بر اساس آن کلید باشد.
• سرور ورود به سطح رویداد را انجام نمی دهد.
• سرور براساس این درخواست ها عوارض جانبی دیگری ندارد.

به عنوان یک مکانیسم موقت ، خریدار و فروشنده می توانند این سیگنال های مناقصه را از هر سرور ، از جمله یکی از آنها که خودشان کار می کنند ، واکشی کنند. با این حال ، در نسخه انتشار ، درخواست فقط به یک سرور نوع ارزش قابل اعتماد ارسال می شود.

خریداران و فروشندگان می توانند از یک سرور با ارزش کلیدی متداول برای سیستم عامل های سازگار با ماسهبازی حریم خصوصی در Android و وب استفاده کنند.

به روز رسانی های اخیر

• اطلاعات اضافه شده در مورد برنامه ریزی به روزرسانی مخاطبان سفارشی
• ادغام گزارش انتساب اضافه شده با مخاطبان محافظت شده
• جدول زمانی از ویژگی های مخاطبان محافظت شده منتشر شد.
• Fledge به API مخاطبان محافظت شده تغییر نام داده است.
• پیشنهاد اضافه شده برای نمایندگان مخاطبان سفارشی .
• نیاز ناشناس بودن K را برای URL به روزرسانی روزانه حذف کرد.

مخاطبان محافظت شده در بتا است و برای آزمایش در دستگاه های عمومی در دسترس است!

با مخاطبان محافظت شده ، می توانید:

• مخاطبان سفارشی را بر اساس اقدامات قبلی کاربر مدیریت کنید.
• حراج های موجود در دستگاه را با پشتیبانی از فروشنده منفرد یا پشتیبانی از واسطه آبشار آغاز کنید.
• گزارش تصور ورزش پس از انتخاب تبلیغ.

برای شروع ، راهنمای توسعه دهنده مخاطبان محافظت شده را بخوانید. از بازخورد شما قدردانی می شود که ما همچنان به توسعه مخاطبان محافظت شده ادامه می دهیم.

جدول زمانی

ما در ماه های آینده ویژگی های جدیدی را منتشر خواهیم کرد. تاریخ انتشار دقیق بسته به ویژگی متفاوت خواهد بود و این جدول با در دسترس بودن پیوندها به مستندات به روز می شود.

نمای کلی

در تبلیغات موبایل ، تبلیغ کنندگان معمولاً بر اساس نحوه فعالیت قبلاً با برنامه تبلیغ کننده ، نیاز به تبلیغات برای کاربران بالقوه دارند. به عنوان مثال ، توسعه دهنده SportingGoodSapp ممکن است بخواهد با نشان دادن تبلیغات برای یادآوری کاربران برای تکمیل خرید ، به کاربرانی که در سبد خرید باقی مانده اند ، تبلیغ کنند. این صنعت معمولاً این ایده کلی را با اصطلاحاتی مانند "بازاریابی" و "هدف قرار دادن مخاطبان سفارشی" توصیف می کند.

امروزه ، این موارد استفاده معمولاً با به اشتراک گذاشتن اطلاعات متنی در مورد نحوه نمایش آگهی (مانند نام برنامه) و اطلاعات خصوصی مانند لیست مخاطبان با سیستم عامل های AD Tech انجام می شود. با استفاده از این اطلاعات ، تبلیغ کنندگان می توانند تبلیغات مربوطه را در سرورهای خود انتخاب کنند.

API مخاطبان محافظت شده در Android (که قبلاً به عنوان Fledge شناخته می شد) شامل API های زیر برای سیستم عامل های فناوری تبلیغاتی و تبلیغ کنندگان برای پشتیبانی از موارد استفاده مبتنی بر تعامل مشترک به روش هایی است که به اشتراک گذاری هر دو شناسه در برنامه ها و اطلاعات تعامل برنامه کاربر با شخص ثالث محدود می شود.

1. API مخاطبان سفارشی : این متمرکز بر انتزاع "مخاطب سفارشی" است که نمایانگر یک مخاطب تبلیغ کننده با اهداف مشترک است. اطلاعات مخاطبان در دستگاه ذخیره شده است و می تواند با تبلیغات نامزد مربوطه برای مخاطب و ابرداده دلخواه مانند سیگنال های مناقصه همراه باشد. از این اطلاعات می توان برای اطلاع رسانی به پیشنهادات تبلیغ کننده ، فیلتر تبلیغات و ارائه استفاده کرد.
2. AD Selection API : این چارچوبی را فراهم می کند که گردش کار سیستم عامل های تبلیغاتی را که از سیگنال های روی دستگاه استفاده می کنند ، برای تعیین یک تبلیغ "برنده" با در نظر گرفتن تبلیغات نامزد ذخیره شده در محلی و انجام پردازش های اضافی در تبلیغات نامزد که یک پلت فرم AD Tech به دستگاه باز می گردد ، می دهد.

در سطح بالایی ، ادغام به شرح زیر است:

1. SportingGoodSapp می خواهد به کاربران خود یادآوری کند که در صورتی که طی 2 روز خرید را انجام نداده اند ، کالاهای کالایی باقی مانده در سبد خرید خود را خریداری کنند. SportingGoodSapp از API مخاطبان سفارشی برای اضافه کردن کاربر به لیست مخاطبان "محصولات موجود در سبد خرید" استفاده می کند. این پلتفرم این لیست مخاطبان را در دستگاه مدیریت و ذخیره می کند و به اشتراک گذاری با شخص ثالث محدود می شود. SportingGoodSapp با یک بستر تبلیغاتی تبلیغاتی برای نشان دادن تبلیغات خود به کاربران در لیست مخاطبان خود. پلت فرم Ad Tech ابرداده را برای لیست مخاطبان مدیریت می کند و تبلیغات نامزد را ارائه می دهد ، که برای بررسی در اختیار گردش کار انتخاب آگهی قرار می گیرد. این سیستم عامل را می توان پیکربندی کرد تا به طور دوره ای تبلیغات مبتنی بر مخاطب را در پس زمینه واگذار کند . این کمک می کند تا لیست تبلیغات نامزد مبتنی بر مخاطب را با درخواست های ارسال شده به سرورهای تبلیغاتی شخص ثالث در طول فرصت تبلیغاتی (IE درخواست تبلیغات متنی) تازه و نامربوط نگه دارید.

2. هنگامی که کاربر Frisbeegame را در همان دستگاه بازی می کند ، ممکن است یک تبلیغ را مشاهده کند که به آنها یادآوری می کند تا خرید کالاهای باقی مانده در سبد خرید SportingGoodSapp را تکمیل کنند. این امر می تواند توسط Frisbeegame (با یک ADS ADS SDK) فراخوانی AD API برای انتخاب یک آگهی برنده برای کاربر بر اساس هر لیست مخاطبان که ممکن است بخشی از آنها باشد ، حاصل شود (در این مثال ، مخاطبان سفارشی ساخته شده توسط SportingGoodSapp). گردش کار انتخاب آگهی را می توان تنظیم کرد تا تبلیغات بازیابی شده از سرورهای سیستم عامل های تبلیغاتی را در نظر بگیرد ، علاوه بر تبلیغات مربوط به دستگاه های مربوط به مخاطبان سفارشی و سایر سیگنال های روی دستگاه. گردش کار همچنین می تواند توسط بستر تبلیغاتی AD Tech و ADS SDK با مناقصه سفارشی و منطق امتیاز دهی برای دستیابی به اهداف تبلیغاتی مناسب تنظیم شود. این رویکرد علاقه کاربر یا داده های تعامل برنامه را قادر به اطلاع رسانی در انتخاب تبلیغات می کند ، در حالی که به اشتراک گذاری این داده ها با شخص ثالث محدود می شود.

3. برنامه تبلیغاتی یا SDK پلت فرم تبلیغی تبلیغات تبلیغاتی را ارائه می دهد.

4. این پلتفرم گزارش برداشت و نتایج انتخاب AD را تسهیل می کند. این قابلیت گزارش دهی مکمل API گزارش انتساب است. سیستم عامل های AD Tech ممکن است بر اساس نیازهای گزارشگری خود سفارشی شوند.

دسترسی به مخاطبان محافظت شده در API های Android

سیستم عامل های AD Tech برای دسترسی به API مخاطبان محافظت شده باید ثبت نام کنند. برای اطلاعات بیشتر به ثبت نام در حساب Sandbox حریم خصوصی مراجعه کنید.

مدیریت مخاطبان سفارشی

مخاطب سفارشی

مخاطب سفارشی گروهی از کاربران را نشان می دهد که توسط تبلیغ کننده با اهداف یا علایق مشترک تعیین می شود. یک برنامه یا SDK ممکن است از مخاطب سفارشی برای نشان دادن مخاطبان خاصی مانند شخصی که "مواردی را در سبد خرید خود باقی مانده است" یا "سطح مبتدی را به پایان رسانده است" از یک بازی استفاده کند. این پلتفرم اطلاعات مخاطبان را به صورت محلی در دستگاه حفظ و ذخیره می کند و در معرض کدام مخاطبان سفارشی کاربر قرار نمی گیرد. مخاطبان سفارشی از گروه های مورد علاقه مخاطبان محافظت شده Chrome متمایز هستند و نمی توانند در وب و برنامه ها به اشتراک گذاشته شوند. این به محدودیت به اشتراک گذاری اطلاعات کاربر کمک می کند.

یک برنامه تبلیغ کننده یا SDK یکپارچه ممکن است بر اساس ، به عنوان مثال ، تعامل کاربر در یک برنامه ، به مخاطب سفارشی بپیوندد یا به آنها اجازه دهد .

ابرداده مخاطبان سفارشی

هر مخاطب سفارشی حاوی ابرداده زیر است:

• مالک: نام بسته برنامه مالک. این به طور ضمنی روی نام بسته برنامه تماس گیرنده تنظیم شده است.
• خریدار: شبکه تبلیغاتی خریدار که تبلیغات این مخاطب سفارشی را مدیریت می کند. خریدار همچنین نماینده ای است که ممکن است به مخاطبان سفارشی دسترسی پیدا کند و اطلاعات مربوط به تبلیغات مربوطه را واگذار کند. خریدار به دنبال فرمت ETLD+1 مشخص شده است.
• نام: یک نام یا شناسه دلخواه برای مخاطبان سفارشی ، مانند کاربر که دارای "رها کننده سبد خرید" است. این ویژگی می تواند به عنوان مثال یکی از معیارهای هدفمند در کمپین های تبلیغاتی تبلیغ کننده یا رشته پرس و جو در URL برای واکشی کد مناقصه استفاده شود.
• زمان فعال سازی و زمان انقضا: این زمینه ها پنجره زمانی را تعریف می کنند که این مخاطب سفارشی مؤثر باشد. این پلتفرم از این اطلاعات برای برداشت عضویت از مخاطبان سفارشی استفاده می کند. زمان انقضا نمی تواند از یک پنجره حداکثر برای محدود کردن عمر مخاطب سفارشی تجاوز کند.
• URL به روزرسانی روزانه: URL که این پلتفرم برای واکشی تبلیغات نامزد و سایر ابرداده های تعریف شده در زمینه های "سیگنال های مناقصه کاربر" و "سیگنال های مناقصه قابل اعتماد" به صورت مکرر تعریف شده است. برای اطلاعات بیشتر ، به بخش نحوه واکشی تبلیغات نامزد برای مخاطبان سفارشی مراجعه کنید.
• سیگنال های مناقصه کاربر: سیگنال های خاص برای پلتفرم AD برای هرگونه پیشنهاد تبلیغات بازاریابی. نمونه هایی از سیگنال ها عبارتند از: مکان درشت کاربر ، محلی ترجیحی و غیره.
• داده های پیشنهادی قابل اعتماد: بسترهای نرم افزاری AD Tech برای اطلاع رسانی در مورد بازیابی و امتیاز دهی به داده های زمان واقعی متکی هستند. به عنوان مثال ، یک تبلیغ ممکن است از بودجه خارج شود و باید سریعاً از خدمت خودداری کند. یک AD-Tech می تواند یک نقطه پایانی URL را از جایی که می توان این داده های زمان واقعی را می توان تعریف کرد و مجموعه کلیدهایی که برای آن نیاز به جستجوی زمان واقعی است ، تعریف کند. سرور این درخواست یک سرور قابل اعتماد خواهد بود که توسط پلت فرم Ad Tech مدیریت می شود.
• URL منطق مناقصه: URL که این پلتفرم برای واکشی کد مناقصه از بستر جانبی تقاضا استفاده می کند. این پلتفرم هنگام آغاز حراج تبلیغ ، این مرحله را انجام می دهد.
• تبلیغات: لیستی از تبلیغات نامزد برای مخاطبان سفارشی. این شامل ابرداده تبلیغاتی خاص برای پلتفرم تبلیغاتی و URL برای ارائه تبلیغات است. هنگامی که حراج برای مخاطبان سفارشی آغاز می شود ، این لیست از ابرداده AD در نظر گرفته می شود. این لیست از تبلیغات با استفاده از نقطه انتهایی URL روزانه در صورت امکان ، تازه می شود. با توجه به محدودیت منابع در دستگاه های تلفن همراه ، محدودیتی در تعداد تبلیغات وجود دارد که می توانند در مخاطبان سفارشی ذخیره شوند.

هیئت مخاطبان سفارشی

تعریف و پیکربندی مخاطبان سفارشی سنتی معمولاً به فن آوری ها و ادغام های سمت سرور که توسط تکنیک های تبلیغاتی با همکاری مشتریان و شرکای آژانس و تبلیغ کننده هدایت می شوند ، متکی است. API مخاطبان محافظت شده ضمن محافظت از حریم شخصی کاربر ، تعریف و پیکربندی مخاطبان سفارشی را امکان پذیر می کند. برای پیوستن به مخاطب سفارشی ، تکنیک های تبلیغاتی خریدار که حضور SDK در برنامه ها ندارند ، باید با فناوری های تبلیغاتی که حضور در دستگاه های خود دارند ، مانند شرکای اندازه گیری موبایل (MMP) و سیستم عامل های سمت عرضه (SSP) همکاری کنند. API مخاطبان محافظت شده با هدف پشتیبانی از این SDK ها با ارائه راه حل های انعطاف پذیر برای مدیریت مخاطبان سفارشی با فعال کردن تماس گیرندگان دستگاه برای فراخوانی مخاطبان سفارشی به نمایندگی از خریداران. این فرآیند نماینده مخاطبان سفارشی نامیده می شود. با دنبال کردن این مراحل ، نمایندگان مخاطبان سفارشی را پیکربندی کنید:

به مخاطبان سفارشی بپیوندید

پیوستن به مخاطب سفارشی می تواند از دو طریق انجام شود:

joinCustomAudience()

یک برنامه یا SDK می تواند با فراخوانی joinCustomAudience() پس از فوری شیء CustomAudience با پارامترهای مورد انتظار ، به مخاطب سفارشی بپیوندد. در اینجا یک نمونه قطعه کد مصور:

CustomAudience audience = new CustomAudience(
    Buyer = "example-dsp.com",
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    DailyUpdateURL = Uri.parse("https://..."),
    UserBiddingSignals = new JSONObject("{...}"),
    TrustedBiddingURL = Uri.parse("https://..."),
    TrustedBiddingKeys = {'key1","key2", ...,"key n"},
    BiddingLogicURL =  Uri.parse("https://..."),
    Ads = [new AdData(renderUrl = Uri.parse("https://..."),
           metadata = new JSONObject("{...}"), ...];

// Invoke ad services API to join a custom audience.
joinCustomAudience(audience);

fetchAndJoinCustomAudience()

یک برنامه یا SDK می تواند به نمایندگی از یک فناوری تبلیغاتی که با فراخوانی fetchAndJoinCustomAudience() با پارامترهای مورد انتظار ، مانند مثال زیر ، حضور در دستگاه خود را به مخاطب سفارشی بپیوندد ، درخواست کند.

FetchAndJoinCustomAudienceRequest fetchRequest = new FetchAndJoinCustomAudienceRequest(
    // Example: Optional verification token passed inside the fetch URL
    FetchURI = Uri.parse("https://example-dsp.com/...?mytoken=arbitrary1234"),
    // All the following parameters are optional
    Name = "running-shoes",
    ActivationTime = now(),
    ExpirationTime = ActivationTime.plus(30 days),
    UserBiddingSignals = new JSONObject("{...}")
);

fetchAndJoinCustomAudience(fetchRequest);

نقطه پایانی URL ، متعلق به خریدار ، با یک شیء JSON CustomAudience در بدنه پاسخ پاسخ می دهد. خریدار و زمینه های مالک مخاطبان سفارشی نادیده گرفته می شوند (و توسط API خودکار می شوند). API همچنین تقویت می کند که URL به روزرسانی روزانه نیز با ETLD+1 خریدار مطابقت خواهد داشت.

{
 "name": "running-shoes",
 "activation_time": 1680603133000,
 "expiration_time": 1680803133000,
 "user_bidding_signals" : {"signal1": "value"},
 "trusted_bidding_data": {
    "trusted_bidding_uri": "https://example-dsp.com/.."
    "trusted_bidding_keys": ["k1", "k2"],
 },
 "bidding_logic_uri": "https://example-dsp.com/...",
 "daily_update_uri": "https://example-dsp.com/...",
 "ads": [
   {
     "render_uri": "https://example-dsp.com/...",
     "metadata": {},
     "ad_filters": {
       "frequency_cap": {
         "win": [
           {
             "ad_counter_key": 1,
             "max_count": 2,
             "interval_in_seconds": 60
           },
         ],
         "view": [
           {
             "ad_counter_key": 2,
             "max_count": 10,
             "interval_in_seconds": 3600
           },
         ]
       },
       "app_install": {
         "package_names": [
           "package.name.one",
           "package.name.two", ...
         ]
       }
     }
   },
   ...
 ]
}

API fetchAndJoinCustomAudience() هویت خریدار را از ETLD+1 fetchUri تعیین می کند. از هویت خریدار CustomAudience برای انجام همان چک های ثبت نام و مجوز برنامه انجام شده توسط joinCustomAudience() استفاده می شود و با پاسخ واکشی قابل تغییر نیست. صاحب CustomAudience نام بسته برنامه تماس است. اعتبار دیگری از fetchUri غیر از بررسی ETLD+1 وجود ندارد ، و به ویژه ، هیچ چک K-Anon وجود ندارد. fetchAndJoinCustomAudience() API درخواست HTTP را برای fetchUri صادر می کند و انتظار دارد یک شیء JSON نماینده مخاطبان سفارشی باشد. همان محدودیت های اجباری ، اختیاری و مقادیر پیش فرض برای قسمتهای شیء مخاطبان سفارشی برای پاسخ استفاده می شود. در مورد الزامات و محدودیت های فعلی در راهنمای توسعه دهنده ما بیاموزید.

هرگونه پاسخ خطای HTTP از طرف خریدار باعث ناکامی fetchAndJoinCustomAudience می شود. به طور خاص پاسخ وضعیت HTTP از 429 (درخواست های بیش از حد) درخواست های برنامه فعلی را برای یک دوره تعریف شده به شما مسدود می کند. اگر پاسخ از خریدار نادرست باشد ، تماس API نیز از بین می رود. خرابی ها به تماس گیرنده API که مسئول امتحان مجدد است به دلیل خرابی های موقت (مانند سرور پاسخ نمی دهد) یا رسیدگی به خرابی های مداوم (مانند خرابی اعتبار داده یا سایر خطاهای غیر ترانزیتی با ارتباط با سرور) گزارش شده است.

شیء CustomAudienceFetchRequest به تماس گیرنده API اجازه می دهد تا با استفاده از خصوصیات اختیاری که در مثال بالا نشان داده شده است ، اطلاعاتی را برای مخاطبان سفارشی تعریف کند. در صورت تنظیم درخواست ، این مقادیر با پاسخ خریدار دریافت شده توسط پلت فرم قابل بازنویسی نیستند. API مخاطبان محافظت شده زمینه ها را در پاسخ نادیده می گیرد. اگر آنها در درخواست تنظیم نشده باشند ، باید آنها را در پاسخ تنظیم کنند ، زیرا این زمینه ها برای ایجاد مخاطب سفارشی لازم هستند. نمایندگی JSON از محتوای CustomAudience که به طور جزئی توسط تماس گیرنده API تعریف شده است ، در درخواست دریافت به fetchUri در یک هدر ویژه X-CUSTOM-AUDIENCE-DATA درج شده است. اندازه فرم سریال داده های مشخص شده برای مخاطبان سفارشی به 8kB محدود می شود. اگر اندازه از آن فراتر رود ، تماس API fetchAndJoinCustomAudience از بین می رود.

فقدان چک K-Anon به شما امکان می دهد از fetchUri برای تأیید خریدار استفاده کنید و به اشتراک گذاری اطلاعات بین خریدار و SDK امکان پذیر است. برای تسهیل تأیید مخاطبان سفارشی ، خریدار امکان پذیر است که یک نشانه تأیید را ارائه دهد. دستگاه ON SDK باید این نشانه را در fetchUri شامل شود تا نقطه پایانی که توسط خریدار میزبان می تواند محتویات مخاطبان سفارشی را واگذار کند و از نشانه تأیید استفاده کند تا تأیید کند که عملیات fetchAndJoinCustomAudience() مطابق با خریدار است و از یک شریک قابل اعتماد در دستگاه خود سرچشمه می گیرد. برای به اشتراک گذاشتن اطلاعات ، خریدار می تواند با تماس گیرنده در دستگاه موافقت کند که برخی از اطلاعاتی که برای ایجاد مخاطب سفارشی استفاده می شود به عنوان پارامترهای پرس و جو به fetchUri اضافه می شود. این امر به خریدار اجازه می دهد تا تماس ها را ممیزی کند و در صورت استفاده از نشانه اعتبار سنجی توسط یک فناوری تبلیغاتی مخرب برای ایجاد چندین مخاطب مختلف سفارشی استفاده کند.

یادداشتی در مورد تعریف و ذخیره سازی تأیید

• نشانه تأیید برای هیچ هدف توسط API مخاطبان محافظت شده استفاده نمی شود و اختیاری است.

  • نشانه تأیید ممکن است توسط خریدار مورد استفاده قرار گیرد تا تأیید کند که مخاطبان ایجاد شده از طرف آنها انجام می شوند.
  • پیشنهاد API مخاطبان محافظت شده ، نه فرمی برای نشانه تأیید و نه چگونگی انتقال خریدار نشانه تأیید را به تماس گیرنده مشخص نمی کند. به عنوان مثال ، نشانه تأیید می تواند در SDK یا پس زمینه مالک بارگیری شود ، یا می توان آن را توسط SDK مالک از سرور خریدار بازیابی کرد.

مخاطب سفارشی را ترک کنید

صاحب یک مخاطب سفارشی ممکن است با فراخوانی leaveCustomAudience() ، همانطور که در قطعه کد تصویرگر در زیر نشان داده شده است ، ترک کند:

// Invoke ad services API to leave a custom audience.
leaveCustomAudience(buyer, name);

برای کمک به حفظ استفاده از ذخیره سازی و سایر منابع دستگاه ، مخاطبان سفارشی منقضی می شوند و پس از مدت زمان از پیش تعیین شده از فروشگاه دستگاه خارج می شوند. مقدار پیش فرض مشخص می شود. مالک می تواند این مقدار پیش فرض را نادیده بگیرد.

کنترل کاربر

• این پیشنهاد قصد دارد تا به کاربران در لیست برنامه های نصب شده که حداقل یک مخاطب سفارشی ایجاد کرده اند ، به کاربران بیفتد
• کاربران می توانند برنامه ها را از این لیست حذف کنند. حذف همه مخاطبان سفارشی مرتبط با برنامه ها را پاک می کند و از پیوستن برنامه ها به مخاطبان جدید سفارشی جلوگیری می کند.
• کاربران توانایی تنظیم مجدد API مخاطبان محافظت شده را به طور کامل دارند. وقتی این اتفاق بیفتد ، هر مخاطب سفارشی موجود در دستگاه پاک می شود.
• کاربران این توانایی را دارند که از ماسه سنگی حریم خصوصی در اندروید ، که شامل API محافظت شده مخاطبان است ، کاملاً امتناع کنند. اگر کاربر از ماسهبازی حریم خصوصی خودداری کرده باشد ، API مخاطبان محافظت شده در سکوت شکست می خورد.

طراحی این قابلیت اثری در حال انجام است و جزئیات در به روزرسانی بعدی گنجانده می شود.

به روز رسانی های برنامه ریزی شده

راه حل هایی که قبلاً توضیح داده شده است به برنامه یا AD Tech SDK نیاز دارد تا API ها را فراخوانی کند در حالی که برنامه در پیش زمینه است و ویژگی های کامل مخاطبان سفارشی را مستقیماً یا با استفاده از نمایندگان ارائه می دهد. با این حال ، همیشه برای تبلیغ کنندگان و ارائه دهندگان فناوری AD امکان پذیر نیست که مخاطبان را در هنگام استفاده از برنامه در زمان واقعی به کدام یک از مخاطبان تعلق داشته باشد.

برای تسهیل این امر ، این امکان وجود دارد که AD Tech بتواند API scheduleCustomAudienceUpdate() فراخوانی کند. این API به تماس گیرنده اجازه می دهد تا تأخیر را در هنگام برقراری تماس API مشخص کند ، بنابراین زمان اضافی را برای پاسخگویی به فناوری پاسخ دهنده برای پردازش رویدادهای سطح برنامه و تعیین اینکه مخاطبان محافظت شده کاربر باید به آن بپیوندند یا از آن حذف شود ، فراهم می کند.

/**
* API To schedule delayed update events for Custom Audience
*
* @param request Criteria that determine when and where to trigger a call to a
* DSP endpoint to update one or more Custom Audiences
*/

public void scheduleCustomAudienceUpdate(
    @NonNull ScheduleCustomAudienceUpdateRequest request,
    @NonNull @CallBackExecutor Executor executor,
    @NonNull AdServicesOutcomeReceiver<Object, Exception> receiver)

برنامه ریزی شده

public final class ScheduleCustomAudienceUpdateRequest {
  // Required Field
  @NonNull public Uri getUpdateUri() {
    return mUpdateUri;
  }

  // Required Field
  @NonNull public Duration getMinDelay() {
    return mMinDelay;
  }

  //  Required Field
  @NonNull public List<PartialCustomAudience> getPartialCustomAudienceList() {
    return mPartialCustomAudiences;
  }

  //  Optional Field (default false)
  public boolean shouldReplacePendingUpdates () {
    return mShouldReplacePendingUpdates;
  }
}

برنامه ScheduleCustomAudienceUpdateRequest شامل اطلاعات لازم برای ثبت کار تاخیری برای اجرای برنامه با سیستم عامل است. پس از تأخیر مشخص ، یک کار پس زمینه به صورت دوره ای اجرا می شود و درخواست (های) را ارسال می کند. ScheduleCustomAudienceUpdateRequest می تواند حاوی اطلاعات زیر باشد:

• UpdateURI : Endpoint URI که برای واکشی به روزرسانی تماس تلفنی ارسال می شود. هویت خریدار ذاتاً از ETLD+1 استنباط می شود و نیازی به صریح نیست و با پاسخ به روزرسانی قابل تغییر نیست. درخواست GET انتظار دارد که یک شیء JSON حاوی لیستی از اشیاء customAudience باشد.
• تأخیر زمان : زمان تأخیر از زمان برقراری تماس API scheduleCustomAudienceUpdate() برای برنامه ریزی به روزرسانی.

• PartialCustomAudience : API همچنین به SDK روی دستگاه اجازه می دهد تا لیستی از مخاطبان سفارشی جزئی ساخته شده را ارسال کند. این امر به SDK های درون برنامه ای اجازه می دهد تا نقش دوگانه را از کنترل کامل تا جزئی بر مدیریت مخاطبان سفارشی بر اساس مشارکت آنها با DSPS خدمت کنند.

  • این همچنین این API را با API fetchAndJoinCustomAudience() سازگار نگه می دارد که امکان اشتراک گذاری اطلاعات مشابه را فراهم می کند.

• usplacependingupdates : بولی که تعیین می کند که آیا هرگونه به روزرسانی برنامه ریزی شده در انتظار باید لغو شود و با به روزرسانی مفصل در برنامه ریزی فعلی ScheduleCustomAudienceUpdateRequest جایگزین شود. اگر این مجموعه به false باشد و به روزرسانی های درخواست شده قبلاً در همان برنامه در انتظار همان خریدار باشد ، تماس با scheduleCustomAudienceUpdate با این ScheduleCustomAudienceUpdateRequest شکست خواهد خورد. پیش فرض ها به false .

مجوزهای برنامه و کنترل

این پیشنهاد در نظر دارد برنامه ها را کنترل کند تا مخاطبان سفارشی خود را کنترل کند:

• یک برنامه می تواند ارتباطات خود را با مخاطبان سفارشی مدیریت کند.
• یک برنامه می تواند مجوزهای سیستم عامل تبلیغاتی شخص ثالث را برای مدیریت مخاطبان سفارشی از طرف آن اعطا کند.

طراحی این قابلیت اثری در حال انجام است و جزئیات در به روزرسانی بعدی گنجانده می شود.

کنترل پلت فرم فناوری تبلیغی

This proposal outlines ways for ad techs to control their custom audiences:

• Ad techs enroll with the Privacy Sandbox and provide an eTLD+1 domain which matches all URLs for a custom audience.
• Ad techs can partner with apps or SDKs to provide verification tokens that are used to verify a custom audience creation. When this process is delegated to a partner, custom audience creation can be configured to require acknowledgement by the ad tech.
• An ad tech can choose to deactivate joinCustomAudience calls on their behalf and only allow the fetchAndJoinCustomAudience API to enable all call custom audiences. Control can be updated during Privacy Sandbox enrollment. Note the control allows either all ad techs or none. Due to platform limitations, delegation permissions can't be on a per ad tech basis.

Candidate ads and metadata response

Candidate ads and metadata returned from a buy-side platform should include the following fields:

• Metadata: Buy-side, ad tech-specific ads metadata. For example, this may include information about the ad campaign, and targeting criteria such as location and language.
• Render URL: Endpoint for rendering the ad creative.
• Filter: Optional information necessary for the Protected Audience API to filter ads based on on-device data. For more details, read the section on buy side filtering logic .

Ad selection workflow

This proposal aims to improve privacy by introducing the Ad Selection API, which orchestrates auction execution for ad tech platforms.

Ad tech platforms today typically perform bidding and ad selection exclusively on their servers. With this proposal, custom audiences and other sensitive user signals, such as available installed package information, will be accessible only through the Ad Selection API. Additionally for the remarketing use case candidate ads will be fetched out of band (ie not in the context in which ads will be shown). Ad tech platforms will need to prepare to have some parts of their current auction and ad selection logic deployed and executed on the device. Ad tech platforms may consider the following changes to their ad selection workflow:

• Without installed package information available on the server, ad tech platforms may want to send multiple contextual ads back to the device and invoke the ad selection workflow to enable app install-based filtering in order to maximize chances to show a relevant ad.
• Because remarketing ads are fetched out of band, current bidding models may need to be updated. Ad tech platforms may want to create bidding sub-models (the implementation may be based on a pattern called two-tower model) that can work on ads features and contextual signals separately and combine the sub-model outputs on the device to predict bids. This can benefit from both server-side auctions and auctions for any given ad opportunity.

This approach enables the user's app interactions data to inform ads selection, while limiting the sharing of this data with third-parties.

This ad selection workflow orchestrates the on-device execution of ad tech-provided JavaScript code based on the following sequence:

1. Buy-side bidding logic execution
2. Buy-side ad filtering and processing
3. Sell-side decision logic execution

For ad selections that involve custom audiences, the platform will fetch buy side-provided JavaScript code based on the public URL endpoint defined by the custom audience's "Bidding logic URL" metadata. The URL endpoint for sell-side decision code will also be passed as an input to initiate the ad selection workflow.

The design of ad selections that don't involve custom audiences is under active design.

Initiate ad selection workflow

When an app needs to show an ad, the ad tech platform SDK may initiate the ad selection workflow by calling the selectAds() method after instantiating the AdSelectionConfig object with the expected parameters:

• Seller : Identifier for the sell-side ad platform, following the eTLD+1 format
• Decision logic URL : When an ad auction is initiated, the platform will use this URL to fetch JavaScript code from the sell-side platform to score a winning ad.
• Custom audience buyers : A list of buy-side platforms with custom audience-based demand for this auction, following the eTLD+1 format.
• Ad selection signals : Information about the auction (ad size, ad format etc.).
• Seller signals : Supply side platform specific signals.
• Trusted Scoring Signals URL : URL endpoint of sell-side trusted signal from which creative specific realtime information can be fetched from.
• Per buyer signals : Participating demand sides may use this parameter to provide inputs for the auction. For example, this parameter may include comprehensive contextual information useful for determining bids.

The following illustrative code snippet shows an ad tech platform SDK initiating the ad selection workflow by first defining the AdSelectionConfig and then invoking selectAds to get the winning Ad:

AdSelectionConfig myAdSelectionConfig = new AdSelectionConfig {
    Seller = "example-ssp1.com",
    DecisionLogicURL = Uri.parse("https://..."),
    CustomAudienceBuyerList = Arrays.asList("example-dsp1.com","bexample-dsp2.com"),
    AdSelectionSignals = "{"min_price": 10,"auction_attempts": 3}"
    SellerSignals = "{"seller_type": "news", "content_category": "sports","mature_ads_accepted" :"false"}"
    PerBuyerSignals = " {"buyer1Name": {"key1" : "value1"},
                         "buyer2Name": {"key1" : "value1", "key2" : "value2" }"
};

// Invoke ad services API to initiate ad selection workflow.
Ad winningAd = selectAds(myAdSelectionConfig);

Buy-side bidding logic

The bidding logic is typically provided by buy-side platforms. The purpose of the code is to determine bids for candidate ads. It may apply additional business logic to determine the result.

The platform will use the custom audience's "Bidding logic URL" metadata to fetch the JavaScript code which should include the function signature below:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ...};
}

The generateBid() method returns the calculated bid amount. The platform will invoke this function for all ads (contextual or remarketing) sequentially. If there are multiple bidding logic providers, the system does not guarantee the execution sequence among the providers.

The function expects the following parameters:

• Ad : The ad being considered by the buy-side bidding code. This will be an Ad from an eligible custom audience
• Auction signals : Sell-side, platform-specific signals.
• Per buyer signals : Participating demand sides may use this parameter to provide inputs for the auction. For example, this parameter may include comprehensive contextual information useful for determining bids.
• Trusted bidding signals : Ad tech platforms rely on real-time data to inform ad retrieval and scoring. For instance, an ad campaign may run out of budget and needs to be stopped serving immediately. An Ad-tech can define a URL endpoint from where this real-time data can be fetched and the set of keys for which the real-time lookup needs to be performed. The ad tech platform's managed server that serves this request will be a trusted server managed by the ad tech platform.
• Contextual signals : This may include coarsened timestamp or approximate location information, or cost per click on the ad.
• User signals : This may include information such as available installed package information.

هزینه تبلیغات

In addition to the bid, buy-side platforms have the option to return the cost per click as part of generateBid() . به عنوان مثال:

generateBid(ad, auction_signals, per_buyer_signals, trusted_bidding_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return {'bid': ..., 'adCost': ...,};
}

If this ad is the winner, adCost is stochastically rounded to 8 bits for privacy. The rounded value of adCost is then passed into the contextual_signals parameter in reportWin during impression reporting.

Buy-side filtering logic

Buy-side platforms will be able to filter ads based on additional on-device signals available during the ad selection phase. For example, ad tech platforms can implement frequency capping capabilities here. If there are multiple filtering providers, the system does not guarantee the execution sequence among the providers.

The buy-side filtering logic can be implemented as part of the bidding logic by returning a bid value of 0 for a given ad.

In addition to that, buy-side platforms will be able to signal that a given ad should be filtered based on additional on-device signals available to Protected Audience and that won't leave the device. As we solidify the designs of additional filtering logic, buy-side platforms will follow this same structure to signal that the filtering should happen.

Sell-side scoring logic

The scoring logic is typically provided by the sell-side platform. The purpose of the code is to determine a winning ad based on bidding logic outputs. It may apply additional business logic to determine the result. If there are multiple decision logic providers, the system does not guarantee the execution sequence among the providers. The platform will use the "Decision logic URL" input parameter of the selectAds() API to fetch the JavaScript code which should include the function signature below:

scoreAd(ad, bid, auction_config, trusted_scoring_signals,
        contextual_signals, user_signals, custom_audience_signals) {
    // ...
    return score_for_this_ad;
}

The function expects the following parameters:

• Ad : The Ad being evaluated; output from the generateBid() function.
• Bid : Bid amount output from the generateBid() function.
• Auction config : Input parameter to selectAds() method.
• Trusted Scoring Signals : Ad tech platforms rely on real-time data to inform ad filtering and scoring. For instance, an app publisher may block an ad campaign from showing ads in the app. This data is fetched from trusted scoring signals url parameter of the auction configuration. The server serving this request should be an ad tech-managed trusted server.
• Contextual signal : This may include coarsened timestamp or approximate location information.
• User signal : This may include information such as the app store that initiated the installation of the app.
• Custom audience signal : If the Ad being scored is coming from an on-device custom audience, this will contain information such as the reader and name of the custom audience.

Ad selection code runtime

In the proposal, the system will fetch ad tech platform-provided auction code from configurable URL endpoints and execute on the device. Given the resource constraints on mobile devices, auction code should adhere to the following guidelines:

• The code should finish executing in a predefined amount of time. This bound will apply uniformly to all buyer ad networks. Details of this bound will be shared in a later update.
• The code must be self-contained and not have any external dependencies.

Since the auction code, such as the bidding logic may need access to private user data such as app install sources, the runtime will not provide network or storage access.

زبان برنامه نویسی

Ad tech platform-provided auction code should be written in JavaScript. This would allow ad tech platforms to, for example, share bidding code across platforms that support Privacy Sandbox.

Winning ad rendering

The ad with the highest score is considered the winner of the auction. In this initial proposal, the winning ad is passed into the SDK for rendering.

The plan is to evolve the solution to ensure that information about a user's custom audience membership, or app engagement history, cannot be determined by the app or SDK through information about the winning ad (similar to Chrome's fenced frames proposal) .

Impression and event reporting

Once the ad has been rendered, the winning impression can be reported back to participating buy-side and sell-side platforms. This allows buyers and sellers to include information from the auction, such as the bid or custom audience name, with the winning impression report. Additionally, the sell-side and winning buy-side platform are eligible to receive additional event-level reporting about the winning ad. This provides the ability to include information about the auction (bid, custom audience name etc.) with clicks, views and other ad events. The platform invokes reporting logic in this order:

1. Sell-side reporting.
2. Buy-side reporting.

This gives buy-side and sell-side platforms a way to send important on-device information back to the servers to enable capabilities like real time budgeting, bidding model updates, and accurate billing workflows. This impression reporting support is complementary to the Attribution Reporting API .

There are two steps required to support event reporting: Sell-side and buy-side JavaScript needs to register what event it should receive event reports for, and the sell-side is responsible for reporting event-level information.

Protected Audience provides a mechanism to subscribe to future events related to a winning auction by registering beacons. In a seller's reportResult() JavaScript function, sell-side platforms can register beacons using the platform's registerAdBeacon() function. Similarly, buy-side platforms can call the registerAdBeacon() method from their reportWin() JavaScript function.

registerAdBeacon(beacons)

ورودی:

• event_key : A string denoting which interaction type to register for. This is used as a key to look up the endpoint the platform pings while reporting the results of the auction.
• reporting_url : The URL owned by the ad tech platform for handling the event.

Event keys are string identifiers that are owned by the sell-side SDK responsible for reporting the results of the auction. For a callback to be made, ad techs register beacons with keys that match the keys used by the sell-side when reporting the events. These don't need to be k-anonymous, though there are limits to the quantity and length of keys that can be registered for a given custom audience. If reportEvent() is called, sell-side platforms that ran the auction are always eligible to receive these event reports. Only the winning buy-side platform is eligible to receive these reports.

Sell-side reporting

The platform invokes the reportResult() JavaScript function in the supply side-provided code downloaded from the seller's Decision logic URL parameter for the selectAds() API:

reportResult(render_url, bid, auction_config, contextual_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_url": reporting_url,
                  "signals_for_buyer": signals_for_buyer}};
}

Output: A JSON object containing

• Status: 0 for success, any other value for failure.
• Reporting URL: The platform invokes this URL returned from the function.
• Signals for Buyer: A JSON object to be passed to the buyer's reportWin function.

The supply side may encode relevant signals in the reporting URL to help them gain further insights into the auction and winning ad. For example, it may include signals below:

• Ad render URL
• Winning bid amount
• نام برنامه
• Query identifiers
• Signals for buyer: To support data sharing between supply side and demand side, the platform passes this return value as an input parameter to demand side reporting code.

Buy-side reporting

The platform invokes the reportWin() JavaScript function in the demand side-provided code downloaded from the Bidding logic URL metadata of the custom audience associated with the auction.

reportWin(render_url, bid, auction_signals, per_buyer_signals,
        signals_for_buyer, contextual_signals, custom_audience_signals) {
    // ...
    beacons = {"click":clickUri}
    registerAdBeacon(beacons)
    return {
      "status": 0,
      "results": {"reporting_uri": reporting_uri}};
}

ورودی:

• auction_signals and per_buyer_signals are fetched from AuctionConfig . Any information that the buy-side platform needs to pass into the reporting URL may come from this datum.
• signals_for_buyer is the output of the sell-side reportResult. This provides the sell-side platform with an opportunity to share data with the buy-side platform for reporting purposes.
• contextual_signals contains information such as app name and custom_audience_signals contains the custom audience information. Other information may be added in the future.

خروجی:

• Status: 0 for success, any other value for failure.
• Reporting URL: The platform invokes this URL returned from the function.

Reporting Events

Reporting events is only possible after impression reporting for the auction has completed. The sell-side SDK is responsible for reporting any events. The platform exposes an API that takes a ReportEventRequest that specifies the recently run auction, the event key that is reported, the data associated with that key, whether the report should be sent to the buyer or the seller (or both), and an optional input event for ad events. The client defines the event key and collection of data to report.

ReportEventRequest request = new ReportEventRequest(
  AdSelectionId = ad_selection_id,
  event_key = "view"
  event_data = "{ "viewTimeInSeconds" :1 }",
  reporting_destinations =
    FLAG_REPORTING_DESTINATION_SELLER |
      FLAG_REPORTING_DESTINATION_BUYER,
  input_event = clickInputEvent // or null for view
  )

reportEvent(request)

ورودی:

• ad_selection_id needs to be an AdSelectionId of a recently run auction retrieved from the AdSelectionOutcome .
• event_key is a sell-side defined string describing the interaction event.
• event_data is a string representing the data associated with the event_key
• reporting_destinations is a bit mask set using flags provided by the platform. It can be one of FLAG_REPORTING_DESTINATION_SELLER or FLAG_REPORTING_DESTINATION_BUYER , or both.
• input_event (optional) is used for integration with Attribution Reporting API. It is either an InputEvent object (for a click event) or null (for a view event). See Attribution Reporting API Integration for more details on this parameter.

After the sell-side SDK invokes reportEvent and, depending on the reporting_destinations flag, the platform attempts to match the event_key to the keys registered by buyers and sellers in their reportWin and reportResult JavaScript functions. If there is a match, the platform POSTs the event_data to the associated reporting_url . The content type of the request is plain text with the body being the event_data . This request is made as best effort and fails silently in the event of a network error, server error response, or if no matching keys were found.

Attribution Reporting API integration

To support buyers who participate in a Protected Audience auction, we are providing cross-API functionality across the Protected Audience and Attribution Reporting APIs (ARA). This functionality enables ad techs to evaluate their attribution performance across various remarketing tactics, so that they can understand which types of audiences deliver the highest ROI.

Through this cross-API integration, adtechs can:

• Create a key-value map of URIs to be used for both 1) ad interaction reporting and 2) source registration.
• Include auction data from the Protected Audience auction in their source-side key mapping for aggregate summary reporting (using the Attribution Reporting API) See the ARA design proposal for more information.

When a user sees or clicks on an ad:

• The URL used to report those events interactions using Protected Audience will provide the necessary data to the buyer to be used to register a view or click as an eligible source with the Attribution Reporting API.
• The ad tech may choose to pass CustomAudience (or other relevant contextual information about the ad such as ad placement or view duration) using that URL so this metadata can propagate down to summary reports when the ad tech is reviewing aggregate campaign performance.

Enabling source registration

reportEvent() will accept a new optional parameter InputEvent . Winning buyers who register ad beacons can choose which reportEvent reports get registered with Attribution Reporting APIs as a registered source. The request header Attribution-Reporting-Eligible will be added to all event reporting requests sent from reportEvent() . Any responses with appropriate ARA headers will be parsed in the same way any other regular ARA source registration response would be. See Attribution Reporting API explainer for how to register a source URL .

Because ARA on Android supports view and click events, InputEvents are used to distinguish between the two types. Just as in ARA source registration, the reportEvent() API will interpret a platform-verified InputEvent as a click event. If the InputEvent is missing, null, or invalid, the source registration will be considered a view.

Note the post-auction eventData may contain sensitive information, so the platform drops the eventData in redirected source registration requests.

Engagement and conversion reporting example

In this example, we'll look at it from the buyer perspective who is interested in associating the data from the auction, rendered ad, and conversion app together.

In this workflow, the buyer coordinates with the seller to send a unique ID into the auction. During the auction, the buyer sends this unique ID with the auction data. During render and conversion time, the data from the rendered ad is also sent out with the same unique ID. Later, the unique ID can be used to associate these reports together.

Workflow: Before the auction starts, the buyer sends a unique ID to the seller as part of their programmatic real-time bidding ("RTB") bid response . The ID can be set as a variable like auctionId . The ID is passed in as perBuyerSignals in the auctionConfig and it becomes available in buyer's bidding logic.

1. During the execution of reportWin , the buyer can register an ad beacon to be triggered during ad render time and for specific interaction events ( registerAdBeacon() ). To associate auction signals for an ad event, set the auctionId as a query param of the beacon URL.
2. During ad render time, the beacons you registered during auction time can be triggered or enhanced with event-level data. The seller must trigger reportEvent() and pass in the event-level data. The platform will ping the buyer's registered ad beacon URL that correlates with the reportEvent() that was triggered.
3. The buyer will register the ad with the Attribution Reporting API by responding to the ad beacon requests with the Attribution-Reporting-Register-Source header. To associate auction signals for a conversion event, set the auctionId in the Register source URL.

After the above process, the buyer will have an auction report, interaction report, and conversion report, that can be correlated using the unique ID that can be used to associate with each other.

Similar workflow applies to a seller if it needs access to attribution data, and the seller can also use a unique ID to send with registerAdBeacon() . The reportEvent() call contains a destination property that can be used to send the report to both the buyer and the seller.

Ad tech platform managed trusted server

Ad selection logic today requires real-time information such as budget depletion status to determine if ad candidates should be selected for auction. Both buy-side and sell-side platforms will be able to get this information from servers they operate. In order to minimize leak of any sensitive information via these servers the proposal calls for the following restrictions:

• The behaviors of these servers, described later in this section, would not leak user information.
• The servers would not create pseudonymous profiles based on the data it sees, ie it will need to be 'trusted'.

Buy side : Once buy side initiates the buy side bidding logic, the platform performs an HTTP fetch of trusted bidding data from the trusted server. The URL is composed by appending the URL and keys present in the Trusted Bidding Signals metadata of the custom audience being processed. This fetch is done only when processing ads from the on device custom audiences. At this stage, buy side can enforce budgets, check for campaign pause / unpause state, perform targeting, etc.

Below is a sample URL to fetch trusted bidding data, based on trusted bidding signal metadata from the custom audience:

https://www.kv-server.example/getvalues?keys=key1,key2

The response from the server should be a JSON object whose keys are key1, key2, etc., and whose values will be made available to the buyer's bidding functions.

Sell side : Similar to the buy side flow above, sell side may want to fetch information about creatives considered in the auction. For instance, a publisher may want to enforce that certain creatives are not shown in their app based on brand safety concerns. This information can be fetched and made available to the sell side auction logic. Similar to the buy side trusted server lookup, sell side trusted server lookup also happens using an HTTP fetch. The URL is composed by appending the Trusted Scoring Signals URL with render URLs of the creatives for which the data needs to be fetched.

Below is a sample URL to fetch information about creatives considered in the auction, based on creative render URLs:

https://www.kv-server.example/getvalues?renderUrls=render_url1,render_url2

Response from the server should be a JSON object whose keys are render URLs sent in the request.

These servers would operate in a trusted way to offer several security and privacy benefits:

• The server's return value for each key can be trusted to be based only on that key.
• The server does not perform event-level logging.
• The server has no other side effects based on these requests.

As a temporary mechanism, the buyer and seller can fetch these bidding signals from any server, including one they operate themselves. However, in the release version, the request will only be sent to a trusted key-value-type server.

Buyers and sellers could use a common trusted key-value-type server for platforms compatible with Privacy Sandbox on Android and for the Web.