बार-बार आने वाली दर्शक सूचियां

इस दस्तावेज़ में, बार-बार इस्तेमाल की जाने वाली ऑडियंस सूचियों के बारे में बताया गया है. यह Google Analytics Data API v1 की एक ऐडवांस सुविधा है. ऑडियंस की सूची एक्सपोर्ट करने की सुविधा के बारे में जानने के लिए, ऑडियंस एक्सपोर्ट करने के बारे में बुनियादी जानकारी देने वाली गाइड पढ़ें.

बार-बार अपडेट होने वाली ऑडियंस की सूचियां, हर दिन ऑडियंस की सूचियां जनरेट करती हैं. ऐसा ऑडियंस की सदस्यता में बदलाव होने पर किया जाता है, ताकि यह पक्का किया जा सके कि आपके पास सबसे नया डेटा है.

सामान्य (बार-बार नहीं होने वाली) ऑडियंस की सूचियां, ऑडियंस में मौजूद उपयोगकर्ताओं की स्टैटिक सूचियां होती हैं. ये सूचियां, सूची जनरेट होने के समय बनाई जाती हैं.

हर दिन ऑडियंस की नई सूची बनाना

एक दिन के ऑडियंस डेटा को प्रोसेस करने और सदस्यता अपडेट करने में अलग-अलग समय लगता है. इस बात की कोई गारंटी नहीं है कि ऑडियंस की सूची का डेटा 24 घंटे में अपडेट हो जाएगा.

उदाहरण के लिए, भले ही हर दिन एक ही समय पर ऑडियंस की सूची का अनुरोध किया जाए, कुछ दिनों तक ऑडियंस की सूची पिछले दिन की सूची जैसी ही होगी. वहीं, अन्य दिनों में ऑडियंस की सूची अलग होगी और इसमें सदस्यता में हुए बदलावों की जानकारी एक दिन पहले की तुलना में ज़्यादा होगी.

ऑडियंस की सूचियां, सदस्यता में हुए सबसे हाल ही के बदलाव से एक दिन पहले के इवेंट डेटा पर आधारित होती हैं. अगर सदस्यता की स्थिति में रोज़ाना होने वाले बदलावों से पहले ऑडियंस की सूची बनाई जाती है, तो इसमें दो दिन पहले का डेटा इस्तेमाल किया जाएगा. अगर सदस्यता की जानकारी हर दिन अपडेट होने के बाद ऑडियंस की सूची बनाई जाती है, तो इसमें पिछले दिन का डेटा इस्तेमाल किया जाएगा.

बार-बार इस्तेमाल की जाने वाली ऑडियंस की सूची को समय-समय पर पोल करना

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

बार-बार इस्तेमाल की जाने वाली ऑडियंस की सूची बनाना

बार-बार अपडेट होने वाली ऑडियंस की सूची बनाने के लिए, अनुरोध में RecurringAudienceList ऑब्जेक्ट का इस्तेमाल करके, recurringAudienceLists.create तरीके को कॉल करें. ये पैरामीटर ज़रूरी हैं:

• audience फ़ील्ड में, ऑडियंस का मान्य नाम. इसे properties/{propertyId}/audiences/{audienceId} के तौर पर फ़ॉर्मैट किया गया है. इस वैल्यू को पाने के लिए, Google Analytics Admin API v1 के audiences.list तरीके का इस्तेमाल किया जा सकता है. audiences.list रिस्पॉन्स के Audience.name फ़ील्ड में, ऑडियंस का नाम होता है.
• dimensions फ़ील्ड में डाइमेंशन की मान्य सूची. इस तरीके के साथ काम करने वाले डाइमेंशन की सूची, ऑडियंस एक्सपोर्ट स्कीमा के दस्तावेज़ में देखी जा सकती है. ऑडियंस की सूची में, सिर्फ़ इस फ़ील्ड में बताए गए डाइमेंशन का डेटा शामिल किया जाता है.

बार-बार इस्तेमाल की जाने वाली ऑडियंस की सूची बनाने के अनुरोध का एक सैंपल यहां दिया गया है:

एचटीटीपी अनुरोध

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists
{
  "audience": "properties/1234567/audiences/12345",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ]
}

recurringAudienceLists.create तरीके के जवाब में, name फ़ील्ड में नाम होता है. जैसे, properties/1234567/recurringAudienceLists/123. इसका इस्तेमाल, बाद की क्वेरी में किया जा सकता है. इससे, बार-बार इस्तेमाल होने वाली ऑडियंस की इस सूची के लिए कॉन्फ़िगरेशन मेटाडेटा को वापस पाया जा सकता है. इसके अलावा, कॉन्फ़िगरेशन मेटाडेटा में, बार-बार इस्तेमाल होने वाली इस ऑडियंस लिस्ट के लिए बनाए गए ऑडियंस लिस्ट इंस्टेंस के संसाधन नाम भी शामिल होते हैं.

एचटीटीपी रिस्पॉन्स

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

पोल के कॉन्फ़िगरेशन का मेटाडेटा

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

यहां एक उदाहरण दिया गया है:

एचटीटीपी अनुरोध

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/recurringAudienceLists/123

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

एचटीटीपी रिस्पॉन्स

{
  "name": "properties/1234567/recurringAudienceLists/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "activeDaysRemaining": 180,
  "audienceLists": [
    "properties/1234567/audienceLists/45678"
  ]
}

किसी प्रॉपर्टी के लिए, बार-बार इस्तेमाल की जाने वाली सभी ऑडियंस सूचियों को लिस्ट करने के लिए, recurringAudienceLists.list का इस्तेमाल किया जा सकता है.

नई ऑडियंस की सूचियों के बारे में एसिंक्रोनस सूचनाएं पाने के लिए, वेबुक का इस्तेमाल करना

recurringAudienceLists.get तरीके का इस्तेमाल करके, बार-बार अपडेट होने वाली किसी ऑडियंस सूची के कॉन्फ़िगरेशन मेटाडेटा को समय-समय पर पोल करने के बजाय, ऑडियंस सूची के उपलब्ध होने पर, आपको Webhook सूचनाएं एसिंक्रोनस तरीके से मिल सकती हैं.

Webhook सूचनाएं कॉन्फ़िगर करने के लिए, बार-बार इस्तेमाल की जाने वाली ऑडियंस की नई सूची बनाते समय, webhookNotification फ़ील्ड तय करें.

Google Analytics Data API v1 में Webhooks इस्तेमाल करने के बारे में ज़्यादा जानने के लिए, Async audience lists with webhooks गाइड पढ़ें.

ऑडियंस एक्सपोर्ट में उपयोगकर्ताओं को वापस पाना

ऑडियंस एक्सपोर्ट में उपयोगकर्ताओं को वापस पाने के लिए, audienceExports.query तरीके को कॉल करें. साथ ही, recurringAudienceLists.get या recurringAudienceLists.list से मिले कॉन्फ़िगरेशन मेटाडेटा से वापस पाए गए ऑडियंस एक्सपोर्ट का नाम डालें.

एचटीटीपी अनुरोध

POST https://analyticsdata.googleapis.com/v1beta/properties/1234567/audienceExports/123:query

अगर ऑडियंस एक्सपोर्ट करने की सुविधा उपलब्ध है, तो ऑडियंस में शामिल उपयोगकर्ताओं की सूची वाला जवाब मिलता है:

एचटीटीपी रिस्पॉन्स

{
  "audienceExport": {
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "ACTIVE",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  },
  "audienceRows": [
    {
      "dimensionValues": [
        {
          "value": "1000276123.1681742376"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000374452.1668627377"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000391956.1652750758"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000410539.1682018694"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "1000703969.1666725875"
        }
      ]
    }
  ],
  "rowCount": 5
}