सुरक्षित ऐप्लिकेशन सिग्नल के डेवलपर की गाइड

Protected App Signals API के साथ प्रयोग शुरू करने में डेवलपर की मदद करने के लिए, इस दस्तावेज़ में एपीआई प्लैटफ़ॉर्म के सभी एपीआई के बारे में बताया गया है. साथ ही, टेस्ट एनवायरमेंट सेट अप करने के तरीके और कॉन्फ़िगरेशन और स्क्रिप्ट के उदाहरण भी दिए गए हैं.

ध्यान दें: सुरक्षित ऐप्लिकेशन सिग्नल को चलाने के लिए, ऐसा बिडिंग और नीलामी सर्वर होना ज़रूरी है जो काम करता हो. इसलिए, AWS या Google Cloud पर बिडिंग और नीलामी लागू करने के लिए बताया गया तरीका अपनाएं.

वर्शन इतिहास

जनवरी 2024

PAS MVP रिलीज़ से जुड़ी, डेवलपर की गाइड की पहली रिलीज़

मार्च 2024

Android API के M-2024-05 रिलीज़ और सर्वर साइड कॉम्पोनेंट के अप्रैल 2024 के रिलीज़ के हिसाब से, एपीआई में हुए बदलाव. सबसे अहम बदलाव:

• on-device API के लिए ज़रूरी अनुमतियों के बारे में जानकारी जोड़ी गई
• उपयोगकर्ता के डिवाइस पर सिग्नल के कोटा को मैनेज करने के बारे में जानकारी जोड़ी गई
• कॉन्टेक्स्ट के हिसाब से विज्ञापन वापस पाने और इग्रेस डेटा ट्रैफ़िक की सुविधा से जुड़े बदलावों के साथ, generateBid सिग्नेचर को अपडेट किया गया
• इग्रेस डेटा ट्रैफ़िक की सुविधा के साथ-साथ reportWin दस्तावेज़ अपडेट किया गया
• BYOS विज्ञापन वापस पाने के लिए सहायता हटाने और विज्ञापन वापस पाने वाले यूडीएफ़ के दस्तावेज़ हटाने के लिए, Ad Retrieval API से जुड़े दस्तावेज़ को अपडेट करें

एपीआई की खास जानकारी

Protected Signals API के प्लैटफ़ॉर्म पर, अलग-अलग सिस्टम पर एपीआई के अलग-अलग सबसेट शामिल होते हैं:

• Android एपीआई:
  • सिग्नल क्यूरेशन एपीआई, जिसमें ये शामिल हैं:
  • सिग्नल एपीआई अपडेट करें
  • सिग्नल एन्कोडिंग एपीआई
  • Protected नीलामी के लिए सहायता एपीआई: SDK टूल, इसका इस्तेमाल सुरक्षित ऐप्लिकेशन सिग्नल का इस्तेमाल करके, बिडिंग और नीलामी (B&A) सर्वर पर सुरक्षित नीलामी चलाने के लिए करें.
• सर्वर-साइड एपीआई:
  • सुरक्षित नीलामी वाला एपीआई: JS स्क्रिप्ट की एक सीरीज़, जो बिडिंग और नीलामी सर्वर में चल रही है. इस एपीआई की मदद से, विक्रेता और खरीदार सुरक्षित नीलामी को लागू करने का लॉजिक लिख सकते हैं.
  • Ad Retrieval API: खरीदार के बिडिंग सर्वर को उपलब्ध कराई गई प्रासंगिक और उपयोगकर्ता की जानकारी के आधार पर, उम्मीदवार के विज्ञापनों की सूची उपलब्ध कराने की ज़िम्मेदारी.

Android क्लाइंट

क्लाइंट-साइड पर, सुरक्षित ऐप्लिकेशन सिग्नल की सतह पर तीन अलग-अलग एपीआई होते हैं:

• सिग्नल अपडेट करें: यह Android System API का इस्तेमाल करता है, ताकि डिवाइस पर सिग्नल चुने जा सकें.
• सिग्नल को कोड में बदलने का तरीका: यह JavaScript API है, जिसका इस्तेमाल नीलामी के दौरान सर्वर को भेजे जाने वाले सिग्नल को तैयार करने के लिए किया जाता है.
• सुरक्षित नीलामी से जुड़ी सहायता: बिडिंग और नीलामी सर्वर पर सुरक्षित नीलामी को चलाने में मदद करने वाला एपीआई. यह एपीआई खास तौर पर, Protected App Signals के लिए नहीं है. इसका इस्तेमाल, Protected Audience API की नीलामियों के लिए भी किया जाता है.

ध्यान दें: 'डेवलपर के लिए झलक' में सुरक्षित ऐप्लिकेशन के सिग्नल की मदद से टेस्ट करते समय, आपको एम्युलेटर का इस्तेमाल करने का सुझाव दिया जाता है. ऐसा इसलिए, क्योंकि सेटअप के दौरान आने वाली समस्या को हल करने के लिए, डिवाइस को वाइप करना सबसे अच्छा तरीका है.

सिग्नल एपीआई अपडेट करें

अपडेट सिग्नल एपीआई, विज्ञापन टेक्नोलॉजी से जुड़ी सेवा उपलब्ध कराता है. इससे, खरीदार की तरफ़ से उपयोगकर्ता और ऐप्लिकेशन से जुड़े सिग्नल को रजिस्टर किया जा सकता है. एपीआई, डेलिगेशन मॉडल पर काम करता है. कॉलर एक यूआरआई उपलब्ध कराता है जिससे फ़्रेमवर्क, इनसे जुड़े सिग्नल और नीलामी में इस्तेमाल किए जाने वाले उन सिग्नल को कोड में बदलने के लिए लॉजिक को फ़ेच करता है.

एपीआई के लिए, android.permission.ACCESS_ADSERVICES_PROTECTED_SIGNALS अनुमति की ज़रूरत है.

updateSignals() एपीआई, यूआरआई से JSON ऑब्जेक्ट हासिल करता है. इसमें बताया जाता है कि किन सिग्नल को जोड़ना या हटाना है और उन सिग्नल को नीलामी के लिए कैसे तैयार करना है.

Executor executor = Executors.newCachedThreadPool();
ProtectedSignalsManager protectedSignalsManager
     =  ProtectedSignalsManager.get(context);

// Initialize a UpdateSignalsRequest
UpdateSignalsRequest updateSignalsRequest = new
  UpdateSignalsRequest.Builder(Uri.parse("https://example-adtech1.com/signals"))
      .build();

OutcomeReceiver<Object, Exception> outcomeReceiver = new OutcomeReceiver<Object, Exception>() {
  @Override
  public void onResult(Object o) {
    //Post-success actions
  }

  @Override
  public void onError(Exception error) {
    //Post-failure actions
  };

// Call updateSignals
protectedSignalsManager.updateSignals(updateSignalsRequest,
    executor,
    outcomeReceiver);

यह प्लैटफ़ॉर्म, सिग्नल के अपडेट फ़ेच करने के अनुरोध में दिए गए यूआरआई को एचटीटीपीएस अनुरोध करता है. सिग्नल अपडेट के साथ, रिस्पॉन्स में एक ऐसा एंडपॉइंट शामिल हो सकता है जो रॉ सिग्नल को कोड में बदले गए पेलोड में बदलने के लिए, एन्कोडिंग लॉजिक को होस्ट करता है. सिग्नल के अपडेट, JSON फ़ॉर्मैट में होने चाहिए और इनमें ये कुंजियां हो सकती हैं:

JSON ऑब्जेक्ट के लिए टॉप लेवल की कुंजियां, पांच में से किसी एक निर्देश के मुताबिक होनी चाहिए:

कुंजी	जानकारी
put	एक ही कुंजी से किसी भी मौजूदा सिग्नल को ओवरराइट करते हुए नया सिग्नल जोड़ता है. वैल्यू के लिए यह एक JSON ऑब्जेक्ट है, जहां कुंजियां रखी जाने वाली कुंजी से संबंधित बेस 64 स्ट्रिंग होती हैं और मान रखी जाने वाली वैल्यू से जुड़ी बेस 64 स्ट्रिंग होती हैं.
append	सिग्नल की टाइम सीरीज़ में नया सिग्नल/सिग्नल जोड़ता है और सबसे पुराने सिग्नल को हटा देता है अगर सीरीज़ का साइज़ तय की गई सबसे ज़्यादा संख्या से ज़्यादा हो जाता है, तो नए सिग्नल के लिए जगह बनानी होगी. इसकी वैल्यू एक JSON ऑब्जेक्ट है. इसमें जोड़ी जाने वाली कुंजी से जुड़ी कुंजियां, बेस 64 स्ट्रिंग होती हैं. वहीं, वैल्यू दो फ़ील्ड वाले ऑब्जेक्ट होती हैं: "values" और "maxSignals". "values": टाइम सीरीज़ में जोड़ने के लिए सिग्नल वैल्यू से जुड़ी बेस 64 स्ट्रिंग की सूची. "maxSignals": इस टाइम सीरीज़ में, ज़्यादा से ज़्यादा वैल्यू की अनुमति है. अगर कुंजी से जुड़े सिग्नल की मौजूदा संख्या, MaxSignals से ज़्यादा हो गई है. सबसे पुराने सिग्नल को हटा दिया जाएगा. ध्यान दें कि आपके पास जोड़ी गई कुंजी में जोड़ने का विकल्प भी है. ध्यान दें कि मानों की अधिकतम संख्या से ज़्यादा जोड़ने पर विफल हो जाएगा.
put_if_not_present	सिर्फ़ तब नया सिग्नल जोड़ा जाता है, जब एक ही कुंजी वाला कोई सिग्नल मौजूद न हो. इसकी वैल्यू एक JSON ऑब्जेक्ट है. इसमें कुंजियां, 64 सेकंड वाली बेस 64 स्ट्रिंग होती हैं. ये स्ट्रिंग, उस कुंजी से जुड़ी होती हैं जिसे रखा जाना है. साथ ही, इसकी वैल्यू 644 वर्णों वाली उस वैल्यू से जुड़ी होती हैं जिसे रखा जाना है.
remove	इससे कुंजी के लिए सिग्नल हटा दिया जाता है. इसकी वैल्यू, बेस 64 वाली स्ट्रिंग की सूची है. यह सूची, उन सिग्नल की कुंजियों के मुताबिक होती है जिन्हें मिटाया जाना चाहिए.
update_encoder	यह एंडपॉइंट को अपडेट करने के लिए कार्रवाई देता है. साथ ही, इस्तेमाल किया जा सकने वाला यूआरआई का इस्तेमाल करें. अपडेट से जुड़ी कार्रवाई उपलब्ध कराने की सब-कुंजी "कार्रवाई" है और फ़िलहाल, "रजिस्टर करें" वैल्यू का इस्तेमाल किया जा सकता है. यह ऐसे एंडपॉइंट को रजिस्टर करेगी जो पहली बार दिए जाने पर, मौजूदा एंडपॉइंट को रजिस्टर करेगा या मौजूदा एंडपॉइंट को दिए गए नए एंडपॉइंट से ओवरराइट करेगा. "रजिस्टर" कार्रवाई के लिए एंडपॉइंट देना ज़रूरी है.एन्कोडर एंडपॉइंट उपलब्ध कराने की सब-कुंजी "endpoint" है और मान यूआरआई है स्ट्रिंग.

JSON अनुरोध का एक सैंपल कुछ ऐसा दिखेगा:

{
    "put": {
        "AAAAAQ==": "AAAAZQ==",
        "AAAAAg==": "AAAAZg=="
    },
    "append": {
        "AAAAAw==": {
            "values": [
                "AAAAZw=="
            ],
            "max_signals": 3
        }
    },
    "put_if_not_present": {
        "AAAABA==": "AAAAaQ==",
        "AAAABQ==": "AAAAag=="
    },
    "update_encoder": {
        "action": "REGISTER",
        "endpoint": "https://adtech1.com/Protected App Signals_encode_script.js"
    }
}

सिग्नल का डिवाइस पर कोटा 10-15 केबी के क्रम में होगा. कोटा से ज़्यादा हो जाने पर, PPAPI, FIFO रणनीति का इस्तेमाल करके सिग्नल को हटा देगा. लोगों को हटाने की प्रक्रिया

सिग्नल एन्कोडिंग एपीआई

सुरक्षित नीलामी के दौरान, सर्वर को भेजे जाने के लिए खरीदारों को Java स्क्रिप्ट फ़ंक्शन देना होगा, ताकि डिवाइस पर सेव किए गए सिग्नल को कोड में बदला जा सके. खरीदार, यह स्क्रिप्ट उस यूआरएल को जोड़कर दे सकते हैं जहां इसे UpdateSignal API अनुरोध के किसी भी जवाब में "update_encoder" की कुंजी का इस्तेमाल करके फ़ेच किया जा सकता है. स्क्रिप्ट में नीचे दिया गया हस्ताक्षर होगा:

function encodeSignals(signals, maxSize) {
  let result = new Uint8Array(maxSize);
  // first entry will contain the total size
  let size = 1;
  let keys = 0;
  
  for (const [key, values] of signals.entries()) {
    keys++;
    // In this encoding we only care about the first byte
    console.log("key " + keys + " is " + key)
    result[size++] = key[0];
    result[size++] = values.length;
    for(const value of values) {
      result[size++] = value.signal_value[0];
    }
  }
  result[0] = keys;
  
  return { 'status': 0, 'results': result.subarray(0, size)};
}

signals पैरामीटर, सुरक्षित ऐप्लिकेशन सिग्नल ऑब्जेक्ट की सूचियों के लिए साइज़ 4 के UInt8Arrays के रूप वाली कुंजियों का मैप है. हर सुरक्षित ऐप्लिकेशन सिग्नल ऑब्जेक्ट में तीन फ़ील्ड होते हैं:

• signal_value: सिग्नल की वैल्यू दिखाने वाला UInt8Array.
• creation_time: epoch-सेकंड में सिग्नल के बनने का समय दिखाने वाली संख्या.
• package_name: उस पैकेज का नाम दिखाने वाली स्ट्रिंग जिसने सिग्नल बनाया.

maxSize पैरामीटर वह संख्या है जो आउटपुट के लिए सबसे बड़े मंज़ूर अरे साइज़ की जानकारी देती है.

फ़ंक्शन को दो फ़ील्ड वाले ऑब्जेक्ट को आउटपुट करना चाहिए:

• status: स्क्रिप्ट चलने पर, वैल्यू की संख्या 0 होनी चाहिए.
• results: यह maxSize से कम या इसके बराबर लंबाई वाला UInt8Array होना चाहिए. इस कलेक्शन को नीलामी के दौरान सर्वर पर भेजा जाएगा और इसे prepareDataForAdRetrieval स्क्रिप्ट की मदद से तैयार किया जाएगा.

एन्कोडिंग से, विज्ञापन टेक्नोलॉजी को फ़ीचर इंजीनियरिंग का शुरुआती चरण मिलता है. इसमें वे रॉ सिग्नल को कंप्रेस करके, अपने कस्टम लॉजिक के आधार पर जोड़कर बनाए गए वर्शन में बदल सकते हैं. ध्यान दें कि ट्रस्टेड एक्ज़ीक्यूशन एनवायरमेंट (टीईई) में चल रही सुरक्षित नीलामी के दौरान, विज्ञापन टेक्नोलॉजी वाले कस्टम लॉजिक के पास कोड में बदलने से जनरेट हुए सिग्नल पेलोड को पढ़ने का ऐक्सेस होगा. खरीदार के बीऐंडए टीईई में चलने वाले कस्टम लॉजिक को उपयोगकर्ता के तय किए गए फ़ंक्शन (यूडीएफ़) के नाम से जाना जाता है. इसके पास, विज्ञापन चुनने (विज्ञापन वापस पाना और बिडिंग) करने के लिए, पब्लिशर ऐप्लिकेशन से मिले कोड में बदले गए सिग्नल और काम के अन्य सिग्नल को पढ़ने का ऐक्सेस होगा.

सिग्नल को कोड में बदलने का तरीका

हर घंटे, रजिस्टर किए गए सिग्नल के साथ कोड में बदलने का लॉजिक उपलब्ध कराने वाले खरीदारों के सिग्नल, नीलामी पेलोड में एन्कोड किए जाएंगे. नीलामी पेलोड के लिए बाइट कलेक्शन डिवाइस पर बना रहता है. साथ ही, इसे एन्क्रिप्ट (सुरक्षित) किया जाता है. सेलर इसे इकट्ठा किए जाने वाले विज्ञापन के डेटा के हिस्से के तौर पर इकट्ठा करेंगे, ताकि इसे सुरक्षित नीलामी में शामिल किया जा सके. जांच करने के लिए, इस कोड में बदलने के समय को इसके हर घंटे के हिसाब से ट्रिगर नहीं किया जा सकता. ऐसा करने के लिए, यह निर्देश दें:

adb shell cmd jobscheduler run -f com.google.android.adservices.api 29

एन्कोडर लॉजिक को वर्शन बनाना

जब विज्ञापन टेक्नोलॉजी के लिए पसंद के मुताबिक बनाए गए एन्कोडर लॉजिक को डाउनलोड करने का अनुरोध किया जाता है, तब विज्ञापन टेक्नोलॉजी एंडपॉइंट, रिस्पॉन्स हेडर में वर्शन नंबर के साथ रिस्पॉन्स दे सकता है. यह वर्शन डिवाइस पर एन्कोडर लॉजिक के साथ बना रहता है. जब रॉ सिग्नल को कोड में बदला जाता है, तो कोड में बदला गया पेलोड, कोड में बदलने के लिए इस्तेमाल किए गए वर्शन के साथ बना रहता है. सुरक्षित नीलामी के दौरान यह वर्शन B&A सर्वर को भी भेजा जाता है, ताकि विज्ञापन की टेक्नोलॉजी, वर्शन के आधार पर अपनी बिडिंग और एन्कोडिंग लॉजिक को अलाइन कर सकें.

Response header for providing encoder version : X_ENCODER_VERSION

सुरक्षित नीलामी सहायता एपीआई

डिवाइस के हिसाब से, सुरक्षित ऐप्लिकेशन के सिग्नल के लिए नीलामी करना सुरक्षित ऑडियंस के लिए नीलामी करने जैसा ही है.

बिडिंग और नीलामी से जुड़ी सेवाएं

सर्वर साइड एपीआई में ये चीज़ें शामिल होती हैं:

• Protected नीलामी API: यह JS फ़ंक्शन या यूडीएफ़ की सीरीज़ होती है. इसे खरीदार और सेलर, अपने मालिकाना हक वाले B&A कॉम्पोनेंट पर डिप्लॉय कर सकते हैं. इससे बिडिंग और नीलामी का लॉजिक तय करने में मदद मिलती है.
• विज्ञापन वापस पाने का एपीआई: खरीदार इस एपीआई को लागू करने के लिए एक REST एंडपॉइंट लागू कर सकते हैं, जो सुरक्षित ऐप्लिकेशन सिग्नल नीलामी के लिए कैंडिडेट विज्ञापनों का सेट उपलब्ध कराने के लिए ज़िम्मेदार होगा.

सुरक्षित नीलामी का एपीआई

Protected ऑक्शन एपीआई में JS API या यूडीएफ़ शामिल होता है. इस एपीआई का इस्तेमाल करके, खरीदार और सेलर अपनी नीलामी और बिडिंग के लॉजिक को लागू कर सकते हैं.

खरीदार विज्ञापन तकनीक यूडीएफ़

EarlyDataForAdRetrieval यूडीएफ़

इससे पहले कि सुरक्षित ऐप्लिकेशन सिग्नल का इस्तेमाल टीईई से विज्ञापन वापस पाने की सेवा से विज्ञापनों को फ़ेच करने के लिए किया जा सके, खरीदारों को सुरक्षित ऐप्लिकेशन सिग्नल और विक्रेता से मिले अन्य डेटा को डिकोड और तैयार करना होगा. खरीदार prepareDataForAdRetrieval यूडीएफ़ आउटपुट, विज्ञापन वापस पाने की सेवा को पास कर दिया जाता है, ताकि बिडिंग के लिए टॉप k कैंडिडेट विज्ञापन फिर से हासिल किए जा सकें.

// Inputs
// ------
// encodedOnDeviceSignals: A Uint8Array of bytes from the device.
// encodedOnDeviceSignalsVersion: An integer representing the encoded
//   version of the signals.
// sellerAuctionSignals: Information about auction (ad format, size) derived
//                       contextually.
// contextualSignals: Additional contextual signals that could help in
//                    generating bids.
//
// Outputs
// -------
// Returns a JSON structure to be used for retrieval.
// The structure of this object is left to the adtech.
function prepareDataForAdRetrieval(encodedOnDeviceSignals,encodedOnDeviceSignalsVersion,sellerAuctionSignals,contextualSignals) {
   return {};
}

बिड यूडीएफ़ जनरेट करें

सबसे अच्छी परफ़ॉर्मेंस वाले कैंडिडेट के विज्ञापन दिखाए जाने के बाद, विज्ञापनों के उम्मीदवारों को खरीदार के कस्टम बिडिंग लॉजिक, generateBid यूडीएफ़ को भेजा जाता है:

// Inputs
// ------
// ads: Data string returned by the ads retrieval service. This can include Protected App Signals
//   ads and related ads metadata.
// sellerAuctionSignals: Information about the auction (ad format, size),
//                       derived contextually
// buyerSignals: Any additional contextual information provided by the buyer
// preprocessedDataForRetrieval: This is the output of this UDF.
function generateBid(ads, sellerAuctionSignals, buyerSignals,
                    preprocessedDataForRetrieval,
                    rawSignals, rawSignalsVersion) {
    return { "ad": <ad Value Object>,
             "bid": <float>,
             "render": <render URL string>,
             'adCost': <optional float ad cost>,
             "egressPayload": <limitedEgressPayload>,
             "temporaryUnlimitedEgressPayload": <temporaryUnlimitedEgressPayload>
    };
}

इस फ़ंक्शन का आउटपुट, किसी विज्ञापन उम्मीदवार के लिए सिंगल बिड है, जिसे ProtectedAppSignalsAdWithBidMetadata के बराबर JSON के तौर पर दिखाया जाता है. फ़ंक्शन, दो अरे भी दिखा सकता है. इन्हें बाद में reportWin को पास किया जाएगा, ताकि मॉडल ट्रेनिंग चालू की जा सके. इग्रेस डेटा ट्रैफ़िक और मॉडल ट्रेनिंग के बारे में ज़्यादा जानकारी के लिए, पास के बारे में जानकारी देने वाले सेक्शन में रिपोर्टिंग सेक्शन देखें

रिपोर्टविन यूडीएफ़

नीलामी खत्म होने पर, नीलामी की सेवा, खरीदारों के लिए रिपोर्टिंग यूआरएल जनरेट करेगी और reportWin यूडीएफ़ (यह वही reportWin फ़ंक्शन है जिसका इस्तेमाल सुरक्षित ऑडियंस के लिए किया जाता है) का इस्तेमाल करके, बीकन को रजिस्टर करेगी. जब क्लाइंट विज्ञापन को रेंडर कर लेगा, तब डिवाइस से इसे पिंग किया जाएगा. इस तरीके का सिग्नेचर, Protected Audience के वर्शन की तरह ही होता है. हालांकि, इसमें दो अतिरिक्त पैरामीटर egressPayload और temporaryUnlimitedEgressPayload शामिल नहीं हैं. मॉडल ट्रेनिंग को चालू करने के लिए, इनका इस्तेमाल किया जाता है और इन्हें generateBid से मिलने वाले नतीजों से अपने-आप भरा जाता है.

// Inputs / Outputs
// ----------------
// See detailed documentation here.
function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
                   buyerReportingSignals,
                   egressPayload, temporaryUnlimitedEgressPayload) {
  // ...
}

सेलर के विज्ञापन टेक्नोलॉजी के यूडीएफ़

ScoreAd यूडीएफ़

इस यूडीएफ़ का इस्तेमाल करके, सेलर यह चुनते हैं कि खरीदारों से मिले कौनसे विज्ञापन नीलामी में जीतेंगे.

function scoreAd(adMetadata, bid, auctionConfig,
                 trustedScoringSignals, bid_metadata) {
  // ...
  return {desirability: desirabilityScoreForThisAd,
              allowComponentAuction: true_or_false};
}

रिपोर्ट के नतीजे यूडीएफ़

इस यूडीएफ़ की मदद से, सेलर इवेंट लेवल पर रिपोर्टिंग कर सकता है. इसमें जीतने वाले विज्ञापन की जानकारी शामिल होती है.

function reportResult(auctionConfig, reporting_metadata) {
  // ...
  registerAdBeacon({"click", clickUrl,"view", viewUrl});
  sendReportTo(reportResultUrl);
  return signalsForWinner;
}

विज्ञापन वापस पाने का एपीआई

MVP रिलीज़ में, विज्ञापन वापस पाने की सेवा, खरीदार से मैनेज होने वाली और होस्ट की गई सेवा होगी. साथ ही, बिडिंग सेवा, इस सेवा से विज्ञापन उम्मीदवारों को फिर से हासिल करती है. अप्रैल 2024 से, विज्ञापन वापस पाने वाले सर्वर को ट्रस्टेड एक्ज़ीक्यूशन एनवायरमेंट (टीईई) में चलना चाहिए. साथ ही, यह जीआरपीसी/प्रोटो इंटरफ़ेस को दिखाएगा. विज्ञापन टेक्नोलॉजी से जुड़ी सेवा देने वाली कंपनियों को इस सर्वर को सेट अप करना होगा. साथ ही, B&A स्टैक डिप्लॉयमेंट के दौरान इसका यूआरएल उपलब्ध कराना होगा. टीईई में चलने वाली इस सेवा को लागू करने के लिए, प्राइवसी सैंडबॉक्स GitHub में उपलब्ध है. बाकी दस्तावेज़ में, हम यह मान रहे हैं कि डिप्लॉयमेंट में इस्तेमाल किया गया कोड यही है.

अप्रैल 2024 से, बीऐंडए वर्शन में कॉन्टेक्स्ट के हिसाब से पाथ पर विज्ञापन दिखाने की सुविधा काम करती है. इस मामले में, बिडिंग सर्वर को आरटीबी सर्वर से भेजे गए विज्ञापन के आइडेंटिफ़ायर की एक सूची मिलेगी. यह सूची, नीलामी की प्रोसेस के दौरान भेजी जाएगी. आइडेंटिफ़ायर को TEE KV सर्वर पर भेजा जाएगा, ताकि बिडिंग के दौरान इस्तेमाल की जाने वाली विज्ञापन से जुड़ी सारी जानकारी फ़ेच की जा सके. उदाहरण के लिए, ad-रेंडर-यूआरएल, मेटाडेटा, और टॉप-k चुनने के लिए विज्ञापन एम्बेड करना. इस दूसरे पाथ को लागू करने के लिए किसी खास लॉजिक की ज़रूरत नहीं होती. इसलिए, हम यहां सिर्फ़ टीईई पर आधारित विज्ञापन वापस पाने के इस्तेमाल के उदाहरण को कॉन्फ़िगर करने के तरीके के बारे में बताएंगे.

यूडीएफ़ को हैंडल करने का अनुरोध

function HandleRequest(requestMetadata, preparedDataForAdRetrieval,
                      deviceMetadata, contextualSignals) {
    return adsMetadataString;
}

जगह:

• requestMetadata: JSON. यूडीएफ़ के लिए, हर अनुरोध के हिसाब से सर्वर मेटाडेटा. अभी के लिए खाली.
• preparedDataForAdRetrieval: इस फ़ील्ड का कॉन्टेंट, विज्ञापन वापस पाने की रणनीति पर निर्भर करता है. संदर्भ के हिसाब से विज्ञापन वापस पाने के मामले में, इस पैरामीटर में रॉ सिग्नल शामिल होंगे. इस डिवाइस से जनरेट हुए और बिडिंग सेवा से पास किए गए रॉ सिग्नल शामिल होंगे. विज्ञापन वापस पाने वाले सर्वर का इस्तेमाल करके टीईई विज्ञापन को फिर से पाने के मामले में, इस पैरामीटर में prepareDataForAdRetrieval यूडीएफ़ का नतीजा शामिल होगा. ध्यान दें: इस चरण में सुरक्षित ऐप्लिकेशन के सिग्नल को डिकोड और एन्क्रिप्ट नहीं किया जाएगा.
• deviceMetadata: JSON ऑब्जेक्ट, जिसमें विक्रेता की विज्ञापन सेवा से फ़ॉरवर्ड किया गया डिवाइस मेटाडेटा मौजूद है. ज़्यादा जानकारी के लिए, बीऐंडए से जुड़े दस्तावेज़ देखें.
  • X-Accept-Language: डिवाइस पर इस्तेमाल की गई भाषा.
  • X-User-Agent: डिवाइस पर उपयोगकर्ता एजेंट का इस्तेमाल किया गया.
  • X-BnA-Client-IP: डिवाइस का आईपी पता.
• contextualSignals: आर्बिट्रेरी स्ट्रिंग, उसी DSP द्वारा ऑपरेट किए जाने वाले प्रासंगिक बोली-प्रक्रिया सर्वर से बनी है. उम्मीद की जाती है कि यूडीएफ़, स्ट्रिंग को डिकोड करके उसका इस्तेमाल कर सकता है. काम के सिग्नल में कोई भी जानकारी हो सकती है, जैसे कि सुरक्षित ऐप्लिकेशन सिग्नल का इस्तेमाल करके पास किए गए सुरक्षित एम्बेड के लिए, एमएल मॉडल वर्शन की जानकारी.

यूडीएफ़ को सफलता मिलने पर स्ट्रिंग दिखानी चाहिए. स्ट्रिंग को बिडिंग सर्वर पर वापस लाया जाता है. इसके बाद, यह इसे generateBid यूडीएफ़ को पास करता है. हालांकि, स्ट्रिंग बस एक सामान्य स्ट्रिंग हो सकती है, लेकिन इस बात की काफ़ी संभावना है कि स्ट्रिंग, सीरियल वाला ऑब्जेक्ट होना चाहिए. इसका स्कीमा, हर विज्ञापन टेक्नोलॉजी से खुद ही तय होता है. जब तक विज्ञापन टेक्नोलॉजी का generateBid लॉजिक, स्ट्रिंग को पहचान सकता है और उसका इस्तेमाल कर सकता है, तब तक स्कीमा पर कोई पाबंदी नहीं होती.

डेवलपमेंट के लिए अपना सिस्टम सेट अप करना

Android

अपना Android डेवलपमेंट एनवायरमेंट सेट अप करने के लिए, आपको ये काम करने होंगे:

1. एक एम्युलेटर (पसंदीदा) या फ़िज़िकल डिवाइस बनाएं, जिस पर Developer Preview 10 इमेज चल रही हो
2. इसे चलाएं:

adb shell am start -n com.google.android.adservices.api/com.android.adservices.ui.settings.activities.AdServicesSettingsMainActivity

इसके बाद, ऐप्लिकेशन के सुझाए गए विज्ञापनों के लिए सहमति देने के लिए दिखाया गया विकल्प चुनें.

1. काम के एपीआई चालू करने के लिए, नीचे दिया गया कमांड चलाएं. आपको समय-समय पर इसे फिर से चलाना पड़ सकता है, क्योंकि बंद किए गए डिफ़ॉल्ट कॉन्फ़िगरेशन को समय-समय पर सिंक किया जाता रहेगा.

adb shell device_config put adservices fledge_custom_audience_service_kill_switch false;  adb shell device_config put adservices fledge_select_ads_kill_switch false; adb shell device_config put adservices fledge_on_device_auction_kill_switch false; adb shell device_config put adservices fledge_auction_server_kill_switch false; adb shell "device_config put adservices disable_fledge_enrollment_check true";  adb shell device_config put adservices ppapi_app_allow_list '\*'; adb shell device_config put adservices fledge_auction_server_overall_timeout_ms 60000;

1. डिवाइस रीस्टार्ट करें.
2. नीलामी की कुंजी के सर्वर पर ले जाने के लिए, डिवाइस की नीलामी कुंजियों को बदलें. गलत कुंजियों को कैश मेमोरी में सेव होने से रोकने के लिए, नीलामी चलाने से पहले इस चरण को चलाना ज़रूरी है.

बिडिंग और नीलामी से जुड़ी सेवाएं

B&A सर्वर सेट अप करने के लिए, सेल्फ़-सर्व सेटअप दस्तावेज़ देखें.

इस दस्तावेज़ में, खास तौर पर खरीदार के लिए सर्वर को कॉन्फ़िगर करने के तरीके पर फ़ोकस किया जाएगा, क्योंकि सेलर के लिए किसी बदलाव की ज़रूरत नहीं है.

ज़रूरी शर्तें

बीऐंडए सर्विस स्टैक को डिप्लॉय करने से पहले, विज्ञापन टेक्नोलॉजी के लिए खरीदार को ये ज़रूरी शर्तें पूरी करनी होंगी:

• पक्का करें कि उन्होंने अपनी टीईई विज्ञापन वापस पाने की सेवा लागू की हो. इससे जुड़ा सेक्शन देखें.
• पक्का करें कि विज्ञापन टेक्नोलॉजी में सभी ज़रूरी यूडीएफ़ (prepareDataForAdRetrieval, generateBid, reportWin, HandleRequest) तय और होस्ट किए गए हों.

यह जानना भी ज़रूरी है कि सुरक्षित नीलामी, B&A के साथ कैसे काम करती है. हालांकि, ऐसा करना ज़रूरी नहीं है.

टेरेस का कॉन्फ़िगरेशन

सुरक्षित ऐप्लिकेशन के सिग्नल का इस्तेमाल करने के लिए, विज्ञापन टेक्नोलॉजी से जुड़ी इन बातों का ध्यान रखें:

• B&A में सुरक्षित ऐप्लिकेशन सिग्नल की सुविधा चालू करें.
• यूआरएल एंडपॉइंट दें, जिनसे prepareDataForAdRetrieval, generateBid और reportWin के लिए नए यूडीएफ़ हासिल किए जा सकते हैं.

इसके अलावा, यह गाइड यह मानती है कि रीमार्केटिंग के लिए B&A का इस्तेमाल करने वाली विज्ञापन तकनीक, रीमार्केटिंग नीलामी के लिए सभी मौजूदा कॉन्फ़िगरेशन फ़्लैग को हमेशा की तरह सेट करना जारी रखेंगी.

खरीदार के विज्ञापन का तकनीकी कॉन्फ़िगरेशन

उदाहरण के तौर पर इस डेमो फ़ाइल का इस्तेमाल करने पर, खरीदारों को ये फ़्लैग सेट करने होंगे:

• सुरक्षित ऐप्लिकेशन सिग्नल चालू करें: सुरक्षित ऐप्लिकेशन सिग्नल का डेटा इकट्ठा करने के लिए इसे चालू किया जाता है.
• सुरक्षित ऐप्लिकेशन सिग्नल के यूआरएल: यह सुरक्षित ऐप्लिकेशन सिग्नल सर्वर के यूआरएल पर सेट होता है.

विज्ञापन टेक्नोलॉजी को इन फ़ील्ड के लिए, प्लेसहोल्डर में सही यूआरएल की जगह सही यूआरएल देना होगा:

module "buyer" {
  # ... More config here.

  runtime_flags = {
    # ... More config here.

    ENABLE_PROTECTED_APP_SIGNALS                  = "true"
    PROTECTED_APP_SIGNALS_GENERATE_BID_TIMEOUT_MS = "60000"
    TEE_AD_RETRIEVAL_KV_SERVER_ADDR               = "<service mesh address of the instance>"
    AD_RETRIEVAL_TIMEOUT_MS                       = "60000"
    BUYER_CODE_FETCH_CONFIG                       = <<EOF
    {
        "protectedAppSignalsBiddingJsUrl": "<URL to Protected App Signals generateBid UDF>",
        "urlFetchTimeoutMs": 60001, # This has to be > 1 minute.
        "urlFetchPeriodMs": 13000000,
        "prepareDataForAdsRetrievalJsUrl": "<URL to the UDF>"
    }
    EOF

  }  # runtime_flags

}  # Module "buyer"

सेलर के विज्ञापन का टेक्नोलॉजी कॉन्फ़िगरेशन

उदाहरण के तौर पर इस डेमो फ़ाइल का इस्तेमाल करके, सेलर को नीचे दिए गए फ़्लैग सेट करने होंगे. (ध्यान दें: यहां सिर्फ़ सुरक्षित ऐप्लिकेशन सिग्नल से जुड़े कॉन्फ़िगरेशन को हाइलाइट किया गया है). विज्ञापन टेक्नोलॉजी को यह पक्का करना होगा कि वे प्लेसहोल्डर में सही यूआरएल को बदल दें:

module "seller" {
  # ... More config here.

  runtime_flags = {
    # ... More config here.

    ENABLE_PROTECTED_APP_SIGNALS                  = "true"

    SELLER_CODE_FETCH_CONFIG                           = <<EOF
  {
    "urlFetchTimeoutMs": 60001, # This has to be > 1 minute.
    "urlFetchPeriodMs": 13000000,
    "protectedAppSignalsBuyerReportWinJsUrls": {"<Buyer Domain>": "URL to reportWin UDF"}
  }
  EOF

  }  # runtime_flags

}  # Module "seller"

केवी और विज्ञापन वापस पाने की सेवाएं

विज्ञापन वापस पाने के लिए चुनी गई रणनीतियों के आधार पर, सिस्टम को KV सेवा के एक या दो इंस्टेंस को डिप्लॉय करना होगा. हम टीईई पर आधारित विज्ञापन वापस पाने के लिए इस्तेमाल किए गए केवी इंस्टेंस इंस्टेंस को Ad Retrieval Server के तौर पर इस्तेमाल करेंगे. साथ ही, उदाहरण के लिए, पाथ के हिसाब से पाथ के आधार पर डेटा वापस पाने में मदद करने वाले इंस्टेंस को, KV Lookup Server के तौर पर देखेंगे.

दोनों मामलों में, सर्वर डिप्लॉयमेंट के लिए KV सर्वर GitHub पर दिए गए दस्तावेज़ का पालन किया जाता है. दोनों केस के बीच अंतर यह होता है कि लुकअप केस, बिना किसी अतिरिक्त कॉन्फ़िगरेशन के काम करता है. हालांकि, डेटा वापस पाने के लिए, डेटा वापस पाने के लॉजिक को लागू करने के लिए, HandleRequest यूडीएफ़ के डिप्लॉयमेंट की ज़रूरत होती है. ज़्यादा जानकारी के लिए, KV सर्वर में शामिल होने की गाइड देखें. ध्यान दें कि B&A के लिए यह उम्मीद की जाती है कि दोनों सेवाएं उसी सेवा मेश में डिप्लॉय की जाएं जिसमें बिडिंग सेवा है.

सेटअप का उदाहरण

इस स्थिति के बारे में सोचें: Protected App Signals API का इस्तेमाल करके, विज्ञापन टेक्नोलॉजी, उपयोगकर्ता के ऐप्लिकेशन के इस्तेमाल के आधार पर काम के सिग्नल सेव करती है. हमारे उदाहरण में, सिग्नल सेव किए जाते हैं, जो कई ऐप्लिकेशन से की गई इन-ऐप्लिकेशन खरीदारी को दिखाते हैं. नीलामी के दौरान, एन्क्रिप्ट (सुरक्षित) किए गए सिग्नल इकट्ठा किए जाते हैं और उन्हें B&A में चल रही सुरक्षित नीलामी में भेजा जाता है. B&A में चल रहे खरीदार के यूडीएफ़, विज्ञापन के कैंडिडेट फ़ेच करने और बिड कंप्यूट करने के लिए सिग्नल का इस्तेमाल करते हैं.

[खरीदार] सिग्नल के उदाहरण

0 की और 1 की वैल्यू वाला सिग्नल जोड़ता है.

{
  "put": {
    "AA==": "AQ=="
  },
  "update_encoder": {
    "action": "REGISTER",
    "endpoint": "https://example.com/example_script"
  }
}

1 और 2 की वैल्यू वाला सिग्नल जोड़ता है.

{
  "put": {
    "AQ==": "Ag=="
  },
  "update_encoder": {
    "action": "REGISTER",
    "endpoint": "https://example.com/example_script"
  }
}

[खरीदार] एन्कोडर सिग्नल का उदाहरण

हर सिग्नल को दो बाइट में कोड में बदलता है, जिसमें पहला बाइट सिग्नल कुंजी का पहला बाइट होता है और दूसरा बाइट, सिग्नल की वैल्यू का पहला बाइट होता है.

function encodeSignals(signals, maxSize) {
  // if there are no signals don't write a payload
  if (signals.size === 0) {
      return {};
  }

  let result = new Uint8Array(signals.size * 2);
  let index = 0;
  
  for (const [key, values] of signals.entries()) {
    result[index++] = key[0];
    result[index++] = values[0].signal_value[0];
  }
  
  return { 'status': 0, 'results': result};
}

[खरीदार] ReadyDataForAdRetrieval का उदाहरण

/**
 * `encodedOnDeviceSignals` is a Uint8Array and would contain
 * the app signals emanating from device. For purpose of the
 * demo, in our sample example, we assume that device is sending
 * the signals with pair of bytes formatted as following:
 * "<id><In app spending>". Where id corresponds to an ad category
 * that user uses on device, and the in app spending is a measure
 * of how much money the user has spent in this app category
 * previously. In our example, id of 0 will correspond to a
 * fitness ad category and a non-zero id will correspond to
 * food app category -- though this info will be useful
 * later in the B&A pipeline.
 *
 * Returns a JSON object indicating what type of ad(s) may be
 * most relevant to the user. In a real setup ad techs might
 * want to decode the signals as part of this script.
 *
 * Note: This example script makes use of only encoded device signals
 * but adtech can take other signals into account as well to prepare
 * the data that will be useful down stream for ad retrieval and
 * bid generation. The max length of the app signals used in this
 * sample example is arbitrarily limited to 4 bytes.
 */
function prepareDataForAdRetrieval(encodedOnDeviceSignals,
                                   encodedOnDeviceSignalsVersion,
                                   sellerAuctionSignals,
                                   contextualSignals) {
  if (encodedOnDeviceSignals.length === 0 || encodedOnDeviceSignals.length > 4 ||
      encodedOnDeviceSignals.length % 2 !== 0) {
     throw "Expected encoded signals length to be an even number in (0, 4]";
  }

  var preparedDataForAdRetrieval = {};
  for (var i = 0; i < encodedOnDeviceSignals.length; i += 2) {
    preparedDataForAdRetrieval[encodedOnDeviceSignals[i]] = encodedOnDeviceSignals[i + 1];
  }
  return preparedDataForAdRetrieval;
}

[खरीदार] विज्ञापन वापस पाने के यूडीएफ़ का नमूना

हमारे उदाहरण में, विज्ञापन की जानकारी वापस लाने वाला सर्वर, हर टॉप k विज्ञापन कैंडिडेट के लिए मेटाडेटा (यानी इस उदाहरण में दिए गए हर विज्ञापन का आईडी) भेजता है. हालांकि, इसमें हर विज्ञापन के लिए ऐसा अन्य डेटा शामिल हो सकता है जो बाद में बिड जनरेट करने में मदद कर सके.

function HandleRequest(requestMetadata, protectedSignals, deviceMetadata,
                      contextualSignals) {
 return "[{\"adId\":\"0\"},{\"adId\":\"1\"}]"

[खरीदार] जनरेट करने के लिए बिड का उदाहरण

/**
 * This script receives the data returned by the ad retrieval service
 * in the `ads` argument. This argument is supposed to contain all
 * the Protected App Signals related ads and the metadata obtained from the retrieval
 * service.
 *
 * `preparedDataForAdRetrieval` argument contains the data returned
 * from the `prepareDataForAdRetrieval` UDF.
 *
 * This script is responsible for generating bids for the ads
 * collected from the retrieval service and ad techs can decide to
 * run a small inference model as part of this script in order to
 * decide the best bid given all the signals available to them.
 *
 * For the purpose of the demo, this sample script assumes
 * that ad retrieval service has sent us most relevant ads for the
 * user and this scripts decides on the ad render URL as well as
 * what value to bid for each ad based on the previously decoded
 * device signals. For simplicity sake, this script only considers
 * 2 types of app categories i.e. fitness and food.
 *
 * Note: Only one bid is returned among all the
 * input ad candidates.
 */
function generateBid(ads, sellerAuctionSignals, buyerSignals, preparedDataForAdRetrieval) {
  if (ads === null) {
    console.log("No ads obtained from the ad retrieval service")
    return {};
  }     
        
  const kFitnessAd = "0";
  const kFoodAd = "1";
  const kBuyerDomain = "https://buyer-domain.com";
        
  let resultingBid = 0;
  let resultingRender = kBuyerDomain + "/no-ad";
  for (let i = 0 ; i < ads.length; ++i) {
    let render = "";
    let bid = 0;
    switch (ads[i].adId) {
      case kFitnessAd:
        render = kBuyerDomain + "/get-fitness-app";
        bid = preparedDataForAdRetrieval[kFitnessAd];
        break;
      case kFoodAd:
        render = kBuyerDomain + "/get-fastfood-app";
        bid = preparedDataForAdRetrieval[kFoodAd];
        break;
      default:
        console.log("Unknown ad category");
        render = kBuyerDomain + "/no-ad";
        break;
    }
    console.log("Existing bid: " + resultingBid + ", incoming candidate bid: " + bid);
    if (bid > resultingBid) {
      resultingBid = bid;
      resultingRender = render;
    }
  }
  return {"render": resultingRender, "bid": resultingBid};
}

[खरीदार] reportWin का उदाहरण

reportWin यूडीएफ़, खरीदार को यह रिपोर्ट करता है कि उसने नीलामी जीत ली है.

function reportWin(auctionSignals, perBuyerSignals, signalsForWinner,
                                       buyerReportingSignals, directFromSellerSignals,
                                       egressPayload,
                                       temporaryUnlimitedEgressPayload) {
  sendReportTo("https://buyer-controlled-domain.com/");
  registerAdBeacon({"clickEvent":"https://buyer-controlled-domain.com/clickEvent"});
  return;
}

[Seller] KV सर्वर सेटअप

सेलर को स्कोरिंग सिग्नल केवी सर्वर सेट अप करना होगा, ताकि विज्ञापन को रेंडर करने वाले यूआरएल से लेकर उससे जुड़े स्कोरिंग सिग्नल को मैप किया जा सके. उदाहरण के लिए: अगर खरीदार ने https:/buyer-domain.com/get-fitness-app और https:/buyer-domain.com/get-fastfood-app को लौटाया, तो https://key-value-server-endpoint.com?client_type=1&renderUrls=<render-url-returned-by-the-buyer> पर GET का इस्तेमाल करके, विक्रेता को एसएफ़ई से क्वेरी करने पर, स्कोरिंग सिग्नल रिस्पॉन्स के ये उदाहरण मिल सकते हैं:

{
   "renderUrls" : {
      "https:/buyer-domain.com/get-fitness-app" : [
         "1",
         "2"
      ],
      "https:/buyer-domain.com/get-fastfood-app" : [
         "3",
         "4"
      ]
   }
}

[सेलर] ScoreAd का उदाहरण

/**
 * This module generates a random desirability score for the Protected App
 * Signals ad in this example. In a production deployment,
 * however, the sellers would want to use all the available signals to generate
 * a score for the ad.
 */
function getRandomInt(max) {
  return Math.floor(Math.random() * max);
}

function scoreAd(adMetadata, bid, auctionConfig,
                                   trustedScoringSignals, deviceSignals,
                                   directFromSellerSignals) {
  return {
    "desirability": getRandomInt(10000),
    "allowComponentAuction": false
  };
}

[सेलर] रिपोर्ट के नतीजे का उदाहरण

function reportResult(auctionConfig, sellerReportingSignals, directFromSellerSignals){
  let signalsForWinner = {};
    sendReportTo("https://seller-controlled-domain.com");
    registerAdBeacon({"clickEvent":
                    "https://seller-controlled-domain.com/clickEvent"});
    return signalsForWinner;
}

सैंपल के तौर पर मिला ऐप्लिकेशन

उदाहरण के लिए, ऊपर बताए गए आसान फ़्लो का इस्तेमाल करने वाला ऐप्लिकेशन बनाने के लिए, एपीआई को कैसे इस्तेमाल किया जा सकता है. हमने सुरक्षित ऐप्लिकेशन सिग्नल का सैंपल ऐप्लिकेशन बनाया है. इसे इस सैंपल डेटा स्टोर करने की जगह में देखा जा सकता है.