ऑडियंस डेटा तय करना

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

Android Protected Audience API का इस्तेमाल करके, उपयोगकर्ता के डिवाइस पर कस्टम ऑडियंस में शामिल हुआ जा सकता है और उससे बाहर निकला जा सकता है. कस्टम ऑडियंस बनाने और उसमें शामिल होने के लिए, आप या तो किसी सर्वर को डेलिगेट कर सकते हैं जिससे आप कस्टम ऑडियंस की कुछ या सभी प्रॉपर्टी फ़ेच करेंगे, या आप एपीआई को सीधे तौर पर कॉल करते समय यह जानकारी दे सकते हैं.

कस्टम ऑडियंस

डिवाइस पर, हर CustomAudience ऑब्जेक्ट की पहचान इन पैरामीटर के कॉम्बिनेशन से होती है:

  • owner: मालिक के ऐप्लिकेशन का पैकेज नाम. यह, कॉल करने वाले ऐप्लिकेशन के पैकेज नाम पर अपने-आप सेट हो जाता है.
  • buyer: खरीदार के विज्ञापन नेटवर्क का आइडेंटिफ़ायर. यह नेटवर्क, इस कस्टम ऑडियंस के लिए विज्ञापन मैनेज करता है.
  • name: कस्टम ऑडियंस के लिए कोई भी नाम या आइडेंटिफ़ायर.

इसके अलावा, CustomAudience को इन ज़रूरी पैरामीटर के साथ बनाया जाना चाहिए:

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

CustomAudience ऑब्जेक्ट के लिए, ये पैरामीटर वैकल्पिक हो सकते हैं:

  • ऐक्टिवेशन का समय: कस्टम ऑडियंस, ऐक्टिवेशन के समय के बाद ही विज्ञापन चुनने और हर दिन के अपडेट में हिस्सा ले सकती है. उदाहरण के लिए, किसी ऐप्लिकेशन के ऐसे उपयोगकर्ताओं को टारगेट करने के लिए यह काम का हो सकता है जो अब ऐप्लिकेशन का इस्तेमाल नहीं करते.
  • समयसीमा खत्म होने का समय: यह आने वाला वह समय है जिसके बाद कस्टम ऑडियंस को डिवाइस से हटा दिया जाता है.
  • उपयोगकर्ता की बिडिंग के सिग्नल: यह JSON स्ट्रिंग है, जिसमें उपयोगकर्ता के सिग्नल शामिल होते हैं. जैसे, उपयोगकर्ता की पसंदीदा जगह. खरीदार का बिडिंग लॉजिक JavaScript, विज्ञापन चुनने की प्रोसेस के दौरान बिड जनरेट करने के लिए इसका इस्तेमाल करता है. इस फ़ॉर्मैट से, विज्ञापन टेक्नोलॉजी प्लैटफ़ॉर्म, अलग-अलग प्लैटफ़ॉर्म पर कोड का फिर से इस्तेमाल कर पाते हैं. साथ ही, JavaScript फ़ंक्शन में इसका इस्तेमाल करना आसान हो जाता है.
  • भरोसेमंद बिडिंग डेटा: यह एचटीटीपीएस यूआरएल और स्ट्रिंग की सूची है, जिसका इस्तेमाल विज्ञापन चुनने की प्रोसेस के दौरान किया जाता है. इससे, भरोसेमंद Key/Value सेवा से बिडिंग के सिग्नल फ़ेच किए जाते हैं.
  • विज्ञापन: यह AdData ऑब्जेक्ट की सूची है. यह सूची, उन विज्ञापनों से जुड़ी होती है जो विज्ञापन चुनने की प्रोसेस में हिस्सा लेते हैं. हर AdData ऑब्जेक्ट में ये चीज़ें शामिल होती हैं:
    • रेंडर यूआरएल: यह एचटीटीपीएस यूआरएल है, जिसकी क्वेरी फ़ाइनल विज्ञापन रेंडर करने के लिए की जाती है.
    • मेटाडेटा: यह JSON ऑब्जेक्ट है, जिसे स्ट्रिंग के तौर पर क्रम से लगाया जाता है. इसमें, विज्ञापन चुनने की प्रोसेस के दौरान खरीदार के बिडिंग लॉजिक के लिए इस्तेमाल की जाने वाली जानकारी शामिल होती है.
    • विज्ञापन फ़िल्टर: यह एक क्लास है, जिसमें विज्ञापन चुनने के दौरान, ऐप्लिकेशन इंस्टॉल करने के विज्ञापन को फ़िल्टर करने और फ़्रीक्वेंसी कैपिंग के लिए ज़रूरी सभी जानकारी शामिल होती है.

कस्टम ऑडियंस को फ़ेच करना और उसमें शामिल होना

fetchAndJoinCustomAudience API की मदद से, खरीदार, कस्टम ऑडियंस में शामिल होने की प्रोसेस को डेलिगेट कर सकते हैं. इसके लिए, वे अपने पार्टनर MMP या SSP के डिवाइस पर मौजूद होने की सुविधा का इस्तेमाल कर सकते हैं.

इसके लिए, डिवाइस पर कॉल करने वाला व्यक्ति (चाहे वह MMP हो या SSP SDK), fetchAndJoinCustomAudienceRequest बनाता है. यह अनुरोध इस तरह दिखता है:

Kotlin

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

val request = FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
    .setName(name)
    .setActivationTime(activationTime)
    .setExpirationTime(expirationTime)
    .setUserBiddingSignals(userBiddingSignals)
    .build()

Java

/**
 * @param fetchUri The URL to retrieve the CA from.
 * (optional)@param name The name of the CA to join.
 * (optional)@param activationTime The time when the CA will activate.
 * (optional)@param expirationTime The time when the CA will expire,
    must be a time in the future otherwise this will fail
 * (optional)@param userBiddingSignals The user bidding signals used at auction.
*/

FetchAndJoinCustomAudienceRequest request =
 new FetchAndJoinCustomAudienceRequest.Builder(fetchUri)
  .setName(name) //Optional
  .setActivationTime(activationTime) //Optional
  .setExpirationTime(expirationTime) //Optional
  .setUserBiddingSignals(userBiddingSignals) //Optional
  .build();

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

fetchUri को खरीदार के सर्वर एंडपॉइंट पर ले जाना चाहिए. यह एंडपॉइंट, कस्टम ऑडियंस का JSON ऑब्जेक्ट दिखाता है. यह ऑब्जेक्ट, यहां दिखाए गए फ़ॉर्मैट के मुताबिक होता है:

//Return a 200 response with data matching the format of the following in the body
{
  "daily_update_uri": "https://js.example.com/bidding/daily",
  "bidding_logic_uri": "https://js.example.com/bidding",
  "user_bidding_signals": {
    "valid": true,
    "arbitrary": "yes"
  },
  "trusted_bidding_data": {
    "trusted_bidding_uri": "https://js.example.com/bidding/trusted",
    "trusted_bidding_keys": [
      "key1",
      "key2"
    ]
  },
  "ads": [
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad1",
      "metadata": {
        "valid": 1
      }
    },
    {
      "render_uri": "https://js.example.com/render/fetch_and_join_ad2",
      "metadata": {
        "valid": 2
      }
    }
  ]
}

एपीआई की ओर से इसे कैसे हल किया जाता है, इस बारे में ज़्यादा जानकारी, CA डेलिगेशन में शामिल होने के लिए डिज़ाइन प्रपोज़ल में देखी जा सकती है.

टेस्ट करना

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

इस फ़्लो का उदाहरण देखने के लिए, GitHub पर मौजूद Privacy Sandbox के सैंपल रिपॉज़िटरी में, फ़ेच कॉल जोड़े गए हैं.

कस्टम ऑडियंस में सीधे तौर पर शामिल होना

अगर आपके पास कस्टम ऑडियंस बनाने और उसमें शामिल होने के लिए ज़रूरी सभी जानकारी पहले से मौजूद है, तो एसिंक्रोनस Protected Audience API कॉल का इस्तेमाल करके, सीधे तौर पर ऐसा किया जा सकता है. कस्टम ऑडियंस को सीधे तौर पर बनाने या उसमें शामिल होने के लिए, यह तरीका अपनाएं:

  1. CustomAudienceManager ऑब्जेक्ट को शुरू करें.
  2. मुख्य पैरामीटर तय करके, CustomAudience ऑब्जेक्ट बनाएं. जैसे, खरीदार का पैकेज और कोई काम का नाम. इसके बाद, JoinCustomAudienceRequest ऑब्जेक्ट के साथ CustomAudience ऑब्जेक्ट को शुरू करें.
  3. एसिंक्रोनस joinCustomAudience() को JoinCustomAudienceRequest ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ कॉल करें.

Kotlin

val customAudienceManager: CustomAudienceManager =
  context.getSystemService(CustomAudienceManager::class.java)

// Minimal initialization of a CustomAudience object
val audience: CustomAudience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build()

// Initialize a custom audience request.
val joinCustomAudienceRequest: JoinCustomAudienceRequest =
  JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build()

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver)

Java

CustomAudienceManager customAudienceManager =
  context.getSystemService(CustomAudienceManager.class);

// Minimal initialization of a CustomAudience object
CustomAudience audience = CustomAudience.Builder()
    .setBuyer(AdTechIdentifier.fromString("my.buyer.domain.name"))
    .setName("example-custom-audience-name")
    .setDailyUpdateUrl(Uri.parse("https://DAILY_UPDATE_URL"))
    .setBiddingLogicUrl(Uri.parse("https://BIDDING_LOGIC_URL"))
    .build();

// Initialize a custom audience request.
JoinCustomAudienceRequest joinCustomAudienceRequest =
    new JoinCustomAudienceRequest.Builder().setCustomAudience(audience).build();

// Request to join a custom audience.
customAudienceManager.joinCustomAudience(joinCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() के नतीजों को मैनेज करना

एसिंक्रोनस joinCustomAudience() तरीका, OutcomeReceiver ऑब्जेक्ट का इस्तेमाल, एपीआई कॉल के नतीजे के बारे में बताने के लिए करता है.

  • onResult() कॉलबैक से पता चलता है कि कस्टम ऑडियंस को बना लिया गया है या उसे अपडेट कर दिया गया है.
  • onError() कॉलबैक से दो संभावित स्थितियों का पता चलता है.
    • अगर JoinCustomAudienceRequest को अमान्य आर्ग्युमेंट के साथ शुरू किया जाता है, तो AdServicesException से पता चलता है कि इसकी वजह IllegalArgumentException है.
    • अन्य सभी गड़बड़ियों के लिए, AdServicesException मिलता है. इससे पता चलता है कि इसकी वजह IllegalStateException है.

joinCustomAudience() के नतीजे को मैनेज करने का एक उदाहरण यहां दिया गया है:

Kotlin

var callback: OutcomeReceiver<Void, AdServicesException> =
    object : OutcomeReceiver<Void, AdServicesException> {
    override fun onResult(result: Void) {
        Log.i("CustomAudience", "Completed joinCustomAudience")
    }

    override fun onError(error: AdServicesException) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error)
    }
};

Java

OutcomeReceiver callback = new OutcomeReceiver<Void, AdServicesException>() {
    @Override
    public void onResult(@NonNull Void result) {
        Log.i("CustomAudience", "Completed joinCustomAudience");
    }

    @Override
    public void onError(@NonNull AdServicesException error) {
        // Handle error
        Log.e("CustomAudience", "Error executing joinCustomAudience", error);
    }
};

कस्टम ऑडियंस से बाहर निकलना

अगर कोई उपयोगकर्ता, किसी कस्टम ऑडियंस के लिए कारोबार की ज़रूरी शर्तें पूरी नहीं करता है, तो कोई ऐप्लिकेशन या SDK, leaveCustomAudience() को कॉल करके, कस्टम ऑडियंस को डिवाइस से हटा सकता है. CustomAudience को उसके यूनीक पैरामीटर के आधार पर हटाने के लिए, यह तरीका अपनाएं:

  1. CustomAudienceManager ऑब्जेक्ट को शुरू करें.
  2. कस्टम ऑडियंस के buyer और name के साथ, LeaveCustomAudienceRequest को शुरू करें. इनपुट फ़ील्ड के बारे में ज़्यादा जानने के लिए, "कस्टम ऑडियंस में सीधे तौर पर शामिल होना." लेख पढ़ें.
  3. एसिंक्रोनस leaveCustomAudience() तरीके को LeaveCustomAudienceRequest ऑब्जेक्ट और काम के Executor और OutcomeReceiver ऑब्जेक्ट के साथ कॉल करें.

Kotlin

val customAudienceManager: CustomAudienceManager =
    context.getSystemService(CustomAudienceManager::class.java)

// Initialize a LeaveCustomAudienceRequest
val leaveCustomAudienceRequest: LeaveCustomAudienceRequest =
    LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build()

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver)

Java

CustomAudienceManager customAudienceManager =
    context.getSystemService(CustomAudienceManager.class);

// Initialize a LeaveCustomAudienceRequest
LeaveCustomAudienceRequest leaveCustomAudienceRequest =
    new LeaveCustomAudienceRequest.Builder()
        .setBuyer(buyer)
        .setName(name)
        .build();

// Request to leave a custom audience
customAudienceManager.leaveCustomAudience(
    leaveCustomAudienceRequest,
    executor,
    outcomeReceiver);

joinCustomAudience() को कॉल करने की तरह, OutcomeReceiver एपीआई कॉल के खत्म होने का सिग्नल देता है. निजता की सुरक्षा के लिए, गड़बड़ी के नतीजे में, इंटरनल गड़बड़ियों और अमान्य आर्ग्युमेंट के बीच कोई अंतर नहीं होता. onResult() कॉलबैक तब कॉल किया जाता है, जब एपीआई कॉल पूरा हो जाता है. भले ही, मैच करने वाली कस्टम ऑडियंस को हटाया गया हो या नहीं.