اصول صادرات مخاطب، مبانی صادرات مخاطب

مخاطبان در Google Analytics 4 به شما این امکان را می دهند که کاربران خود را به روش هایی که برای کسب و کار شما مهم هستند تقسیم بندی کنید. با مخاطبین، می توانید کاربران سایت یا برنامه خود را بر اساس ویژگی های مشترک گروه بندی کنید.

با استفاده از Google Analytics Data API v1 می‌توانید Audiences Exports ایجاد کنید که شامل یک عکس فوری از کاربران در بین مخاطبان است.

ایجاد صادرات مخاطب

Google Analytics Data API v1 از یک رویکرد ناهمزمان برای ایجاد Audience Exports استفاده می کند. ابتدا، برای ایجاد Audience Export از کاربران، درخواستی از متد audienceExports.create لازم است. سپس برای بازیابی کاربران موجود در مخاطب، از روش audienceExports.query استفاده می شود.

علاوه بر این، می‌توانید از audienceExports.get برای بازیابی فراداده‌های پیکربندی در مورد یک Audience Export خاص و audienceExports.list برای فهرست کردن همه Audience Exports برای یک ویژگی استفاده کنید.

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

همه روش‌های Data API v1 نیاز دارند که شناسه ویژگی Google Analytics 4 در یک مسیر درخواست URL به شکل properties/GA4_PROPERTY_ID مشخص شود، مانند:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/audienceExports

گزارش بر اساس داده‌های رویداد Google Analytics جمع‌آوری‌شده در ویژگی Google Analytics 4 ایجاد می‌شود.

اگر از یکی از کتابخانه های سرویس گیرنده Data API استفاده می کنید، نیازی به دستکاری مسیر URL درخواست به صورت دستی نیست. اکثر سرویس گیرندگان API یک پارامتر property را ارائه می دهند که انتظار رشته ای به شکل properties/GA4_PROPERTY_ID را دارد. برای مثال هایی از استفاده از کتابخانه های سرویس گیرنده ، راهنمای شروع سریع را ببینید.

درخواست ایجاد صادرات مخاطب

برای ایجاد Audience Export، با استفاده از شی AudienceExport در یک درخواست، متد audienceExports.create را فراخوانی کنید. پارامترهای زیر مورد نیاز است:

  • یک نام مخاطب معتبر در فیلد audience ، قالب‌بندی شده به‌عنوان properties/{propertyId}/audiences/{audienceId} . برای به دست آوردن این مقدار می توانید از متد audiences.list Google Analytics Admin API v1 استفاده کنید. قسمت Audience.name پاسخ audiences.list حاوی نام مخاطب است.
  • یک لیست معتبر از ابعاد در قسمت dimensions . لیست ابعاد پشتیبانی شده توسط این روش را می توان در مستندات طرحواره صادرات مخاطب یافت. فقط داده‌های ابعاد ذکر شده در این قسمت در صادرات مخاطب گنجانده شده است.

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

درخواست HTTP

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

پاسخ متد audienceExports.create حاوی نام Audience Export در فیلد name است (مانند properties/1234567/audienceExports/123 )، که می تواند در جستارهای بعدی برای بازیابی کاربران از Audience Export استفاده شود.

پاسخ HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

وضعیت آمادگی صادرات مخاطب را جویا شوید

ممکن است چند دقیقه طول بکشد تا Audience Export پس از تماس audienceExports.create ایجاد شود. می توانید با فراخوانی متد audienceExports.get وضعیت آمادگی برای صادرات مخاطب را بدست آورید.

از نام Audience Export (مانند properties/1234567/audienceExports/123 ) که از پاسخ audienceExports.create دریافت کرده‌اید استفاده کنید تا Audience Export را مشخص کنید.

مثال:

درخواست HTTP

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

وضعیت آمادگی برای صادرات مخاطب در قسمت state یک پاسخ بازگردانده می شود. پس از تکمیل تولید Audience Export، وضعیت آن از CREATING به ACTIVE تغییر می کند.

پاسخ HTTP

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

با فراخوانی روش audienceExports.list می توانید وضعیت همه صادرات مخاطبان را بدست آورید.

بازیابی کاربران در صادرات مخاطب

هنگامی که Audience Export ایجاد شده با استفاده از روش audienceExports.create ایجاد شد، متد audienceExports.query را فراخوانی کنید و نام Audience Export را مشخص کنید (مانند properties/1234567/audienceExports/123 ).

درخواست HTTP

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

اگر Audience Export آماده باشد، پاسخی حاوی لیست کاربران در یک مخاطب برگردانده می شود:

پاسخ HTTP

{
  "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
}

انتظارات داده صادرات مخاطب

بخش زیر انتظارات داده را برای عضویت کاربر در صادرات مخاطبان تنظیم می کند.

تازگی داده ها

تازه بودن داده صادرات مخاطب به مدت زمانی است که Google Analytics طول می کشد تا رویدادها را جمع آوری کند، رویدادها را پردازش کند و سپس عضویت کاربر را در مخاطبان به روز کند. اگر کل این فرآیند 24 ساعت طول بکشد، تازه‌سازی داده‌های صادرات مخاطب 24 ساعت است. برای کسب اطلاعات بیشتر به Data Freshness مراجعه کنید.

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

صادرات مخاطب یک عکس فوری است

صادرات مخاطب لیستی از کاربران در یک مخاطب در یک عکس فوری در زمان است. برای بازاریابی مجدد گوگل ادز ، گوگل آنالیتیکس به طور خودکار و پیوسته کاربران را در مخاطبان به Google Ads صادر می کند. در مقابل، با Audience Exports که با استفاده از Data API v1 ایجاد شده است، باید یک Audience Export جدید ایجاد کنید تا آخرین کاربران آن مخاطب را ببینید.

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

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

انقضای صادرات مخاطب

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

محدودیت های کاربر صادرات مخاطب

هنگامی که اندازه یک مخاطب یا دارایی از حد مجاز کاربر فراتر رود، Audience Exports نمونه های نماینده مخاطب را برمی گرداند. این محدودیت ها به نوع دارایی شما (یعنی یک ویژگی استاندارد یا 360) بستگی دارد و در هر صادرات مخاطب به صورت جداگانه اعمال می شود. کاربران بازگشتی کاربرانی در مخاطبان درخواستی هستند و کاربران در نظر گرفته شده کاربرانی هستند که ممکن است عضوی از مخاطب باشند یا نباشند.

نوع حد محدودیت های استاندارد املاک محدودیت های دارایی Analytics 360
Max کاربران بازگشت 2 میلیون 200 میلیون
حداکثر کاربران را در نظر گرفت 10 میلیون 1 میلیارد

گزارش سازگاری هویت

هویت گزارش تصمیم می‌گیرد که چگونه کاربران در گزارش‌ها کپی‌برداری شوند. صادرات مخاطب بر اساس تنظیمات هویت گزارش تغییر نمی کند. Audience Exports همیشه کاربران را با User-ID و سپس ID دستگاه شناسایی می کند.

این بدان معناست که گزارش‌های مربوط به یک مخاطب می‌تواند تعداد کاربران بیشتری را نسبت به صادرات مخاطب نشان دهد. برای مثال، اگر شناسه گزارش‌دهی «مبتنی بر دستگاه» باشد و شناسه کاربری جمع‌آوری شود، گزارش‌ها کاربران را براساس شناسه کاربر کپی نمی‌کنند، اما Audience Exports براساس شناسه کاربر کپی می‌کند.

قوام پس پرکن

وقتی یک مخاطب در Google Analytics ایجاد می‌کنید و بازاریابی مجدد Google Ads را فعال می‌کنید، Google Analytics آن مخاطب را در Google Ads با اعضای اخیراً اضافه شده پر می‌کند . با این حال، گزارش‌های Google Analytics و Audience Exports شامل عضویت مخاطبان پرشده نیست. کاربر باید یک رویداد را پس از ایجاد گزارش و Audience Exports برای نمایش کاربر در آن مخاطب ثبت کند.

برای مثال، اگر کاربری یک رویداد خرید را در 20 ژوئن ثبت کند و شما در 21 ژوئن یک مخاطب «خریداران» ایجاد کنید، احتمالاً باید تا 22 ژوئن منتظر بمانید تا به طور بالقوه آن کاربر را در صادرات مخاطب جدید ببینید. با این حال، آن کاربر تنها در صورتی در صادرات مخاطب قرار خواهد گرفت که کاربر رویدادی را در 21 ژوئن ثبت کرده باشد.

،

مخاطبان در Google Analytics 4 به شما این امکان را می دهند که کاربران خود را به روش هایی که برای کسب و کار شما مهم هستند تقسیم بندی کنید. با مخاطبین، می توانید کاربران سایت یا برنامه خود را بر اساس ویژگی های مشترک گروه بندی کنید.

با استفاده از Google Analytics Data API v1 می‌توانید Audiences Exports ایجاد کنید که شامل یک عکس فوری از کاربران در بین مخاطبان است.

ایجاد صادرات مخاطب

Google Analytics Data API v1 از یک رویکرد ناهمزمان برای ایجاد Audience Exports استفاده می کند. ابتدا، برای ایجاد Audience Export از کاربران، درخواستی از متد audienceExports.create لازم است. سپس برای بازیابی کاربران موجود در مخاطب، از روش audienceExports.query استفاده می شود.

علاوه بر این، می‌توانید از audienceExports.get برای بازیابی فراداده‌های پیکربندی در مورد یک Audience Export خاص و audienceExports.list برای فهرست کردن همه Audience Exports برای یک ویژگی استفاده کنید.

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

همه روش‌های Data API v1 نیاز دارند که شناسه ویژگی Google Analytics 4 در یک مسیر درخواست URL به شکل properties/GA4_PROPERTY_ID مشخص شود، مانند:

  POST  https://analyticsdata.googleapis.com/v1beta/properties/GA4_PROPERTY_ID/audienceExports

گزارش بر اساس داده‌های رویداد Google Analytics جمع‌آوری‌شده در ویژگی Google Analytics 4 ایجاد می‌شود.

اگر از یکی از کتابخانه های سرویس گیرنده Data API استفاده می کنید، نیازی به دستکاری مسیر URL درخواست به صورت دستی نیست. اکثر سرویس گیرندگان API یک پارامتر property را ارائه می دهند که انتظار رشته ای به شکل properties/GA4_PROPERTY_ID را دارد. برای مثال هایی از استفاده از کتابخانه های سرویس گیرنده ، راهنمای شروع سریع را ببینید.

درخواست ایجاد صادرات مخاطب

برای ایجاد Audience Export، با استفاده از شی AudienceExport در یک درخواست، متد audienceExports.create را فراخوانی کنید. پارامترهای زیر مورد نیاز است:

  • یک نام مخاطب معتبر در فیلد audience ، قالب‌بندی شده به‌عنوان properties/{propertyId}/audiences/{audienceId} . برای به دست آوردن این مقدار می توانید از متد audiences.list Google Analytics Admin API v1 استفاده کنید. قسمت Audience.name پاسخ audiences.list حاوی نام مخاطب است.
  • یک لیست معتبر از ابعاد در قسمت dimensions . لیست ابعاد پشتیبانی شده توسط این روش را می توان در مستندات طرحواره صادرات مخاطب یافت. فقط داده‌های ابعاد ذکر شده در این قسمت در صادرات مخاطب گنجانده شده است.

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

درخواست HTTP

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

پاسخ متد audienceExports.create حاوی نام Audience Export در فیلد name است (مانند properties/1234567/audienceExports/123 )، که می تواند در جستارهای بعدی برای بازیابی کاربران از Audience Export استفاده شود.

پاسخ HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.AudienceExport",
    "name": "properties/1234567/audienceExports/123",
    "audience": "properties/1234567/audiences/12345",
    "audienceDisplayName": "Purchasers",
    "dimensions": [
      {
        "dimensionName": "deviceId"
      }
    ],
    "state": "CREATING",
    "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
  }
}

وضعیت آمادگی صادرات مخاطب را جویا شوید

ممکن است چند دقیقه طول بکشد تا Audience Export پس از تماس audienceExports.create ایجاد شود. می توانید با فراخوانی متد audienceExports.get وضعیت آمادگی برای صادرات مخاطب را بدست آورید.

از نام Audience Export (مانند properties/1234567/audienceExports/123 ) که از پاسخ audienceExports.create دریافت کرده‌اید استفاده کنید تا Audience Export را مشخص کنید.

مثال:

درخواست HTTP

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

وضعیت آمادگی برای صادرات مخاطب در قسمت state یک پاسخ بازگردانده می شود. پس از تکمیل تولید Audience Export، وضعیت آن از CREATING به ACTIVE تغییر می کند.

پاسخ HTTP

{
  "name": "properties/1234567/audienceExports/123",
  "audience": "properties/1234567/audiences/12345",
  "audienceDisplayName": "Purchasers",
  "dimensions": [
    {
      "dimensionName": "deviceId"
    }
  ],
  "state": "CREATING",
  "beginCreatingTime": "2023-06-22T23:35:28.787910949Z"
}

با فراخوانی روش audienceExports.list می توانید وضعیت همه صادرات مخاطبان را بدست آورید.

بازیابی کاربران در صادرات مخاطب

هنگامی که Audience Export ایجاد شده با استفاده از روش audienceExports.create ایجاد شد، متد audienceExports.query را فراخوانی کنید و نام Audience Export را مشخص کنید (مانند properties/1234567/audienceExports/123 ).

درخواست HTTP

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

اگر Audience Export آماده باشد، پاسخی حاوی لیست کاربران در یک مخاطب برگردانده می شود:

پاسخ HTTP

{
  "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
}

انتظارات داده صادرات مخاطب

بخش زیر انتظارات داده را برای عضویت کاربر در صادرات مخاطبان تنظیم می کند.

تازگی داده ها

تازه بودن داده صادرات مخاطب به مدت زمانی است که Google Analytics طول می کشد تا رویدادها را جمع آوری کند، رویدادها را پردازش کند و سپس عضویت کاربر را در مخاطبان به روز کند. اگر کل این فرآیند 24 ساعت طول بکشد، تازه‌سازی داده‌های صادرات مخاطب 24 ساعت است. برای کسب اطلاعات بیشتر به Data Freshness مراجعه کنید.

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

صادرات مخاطب یک عکس فوری است

صادرات مخاطب لیستی از کاربران در یک مخاطب در یک عکس فوری در زمان است. برای بازاریابی مجدد گوگل ادز ، گوگل آنالیتیکس به طور خودکار و پیوسته کاربران را در مخاطبان به Google Ads صادر می کند. در مقابل، با Audience Exports که با استفاده از Data API v1 ایجاد شده است، باید یک Audience Export جدید ایجاد کنید تا آخرین کاربران آن مخاطب را ببینید.

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

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

انقضای صادرات مخاطب

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

محدودیت های کاربر صادرات مخاطب

هنگامی که اندازه یک مخاطب یا دارایی از حد مجاز کاربر فراتر رود، Audience Exports نمونه های نماینده مخاطب را برمی گرداند. این محدودیت ها به نوع دارایی شما (یعنی یک ویژگی استاندارد یا 360) بستگی دارد و در هر صادرات مخاطب به صورت جداگانه اعمال می شود. کاربران بازگشتی کاربرانی در مخاطبان درخواستی هستند و کاربران در نظر گرفته شده کاربرانی هستند که ممکن است عضوی از مخاطب باشند یا نباشند.

نوع حد محدودیت های استاندارد املاک محدودیت های دارایی Analytics 360
Max کاربران بازگشت 2 میلیون 200 میلیون
حداکثر کاربران را در نظر گرفت 10 میلیون 1 میلیارد

گزارش سازگاری هویت

هویت گزارش تصمیم می‌گیرد که چگونه کاربران در گزارش‌ها کپی‌برداری شوند. صادرات مخاطب بر اساس تنظیمات هویت گزارش تغییر نمی کند. Audience Exports همیشه کاربران را با User-ID و سپس ID دستگاه شناسایی می کند.

این بدان معناست که گزارش‌های مربوط به یک مخاطب می‌تواند تعداد کاربران بیشتری را نسبت به صادرات مخاطب نشان دهد. برای مثال، اگر شناسه گزارش‌دهی «مبتنی بر دستگاه» باشد و شناسه کاربری جمع‌آوری شود، گزارش‌ها کاربران را براساس شناسه کاربر کپی نمی‌کنند، اما Audience Exports براساس شناسه کاربر کپی می‌کند.

قوام پس پرکن

وقتی یک مخاطب در Google Analytics ایجاد می‌کنید و بازاریابی مجدد Google Ads را فعال می‌کنید، Google Analytics آن مخاطب را در Google Ads با اعضای اخیراً اضافه شده پر می‌کند . با این حال، گزارش‌های Google Analytics و Audience Exports شامل عضویت مخاطبان پرشده نیست. کاربر باید یک رویداد را پس از ایجاد گزارش و Audience Exports برای نمایش کاربر در آن مخاطب ثبت کند.

برای مثال، اگر کاربری یک رویداد خرید را در 20 ژوئن ثبت کند و شما در 21 ژوئن یک مخاطب «خریداران» ایجاد کنید، احتمالاً باید تا 22 ژوئن منتظر بمانید تا به طور بالقوه آن کاربر را در صادرات مخاطب جدید ببینید. با این حال، آن کاربر تنها در صورتی در صادرات مخاطب قرار خواهد گرفت که کاربر رویدادی را در 21 ژوئن ثبت کرده باشد.