ارسال رویدادها

می‌توانید از طریق این راهنمای سریع با ارسال داده‌های رویداد آشنا شوید.

از API مدیریت داده برای هر یک از سناریوهای زیر استفاده کنید:

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

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

  • داده‌های رویداد را برای تبدیل‌های آفلاین گوگل ادز یا تبدیل‌های پیشرفته برای سرنخ‌ها ارسال کنید.

نسخه‌ای از راهنما را که می‌خواهید ببینید انتخاب کنید:

در این راهنمای سریع، مراحل زیر را انجام می‌دهید:

  1. یک Destination برای دریافت داده‌های رویداد آماده کنید.
  2. داده‌های رویداد را برای ارسال آماده کنید.
  3. یک درخواست IngestionService برای رویدادها بسازید.
  4. درخواست را با Google APIs Explorer ارسال کنید.
  5. واکنش‌های موفقیت و شکست را درک کنید.

آماده‌سازی مقاصد

قبل از اینکه بتوانید داده ارسال کنید، باید حداقل یک Destination برای داده‌ها آماده کنید. در اینجا یک نمونه Destination برای استفاده شما آورده شده است:

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID"
    }

فیلدهای یک Destination به شرح زیر است:

operatingAccount

حسابی که رویدادها را دریافت می‌کند.

برای رویدادهایی که به عنوان منبع داده اضافی ارسال می‌شوند، حساب کاربری می‌تواند یک حساب Google Ads یا یک ویژگی Google Analytics باشد. accountType روی GOOGLE_ADS یا GOOGLE_ANALYTICS_PROPERTY تنظیم کنید و accountId روی شناسه مشتری Google Ads یا شناسه ویژگی Google Analytics تنظیم کنید. اگر accountType GOOGLE_ANALYTICS_PROPERTY باشد، اعتبارنامه‌های درخواست باید برای یک کاربر Google Analytics با نقش ویرایشگر یا مدیر برای ویژگی باشد.

برای تبدیل‌های آفلاین و تبدیل‌های پیشرفته برای سرنخ‌ها، حساب عملیاتی باید یک حساب گوگل ادز باشد، بنابراین accountType روی GOOGLE_ADS تنظیم کنید و accountId روی شناسه مشتری گوگل ادز تنظیم کنید.

loginAccount

حسابی که کاربرِ دارای اعتبارنامه به آن دسترسی دارد.

اگر اعتبارنامه‌های OAuth شما برای کاربری است که به حساب مدیریت تبلیغات گوگل دسترسی دارد و operatingAccount یکی از زیرحساب‌های آن است، loginAccount مورد نیاز است. accountId مربوط به loginAccount را روی شناسه حساب مدیریت تنظیم کنید و accountType مربوط به loginAccount را روی GOOGLE_ADS تنظیم کنید.

اگر اعتبارنامه‌های OAuth شما برای کاربری است که دسترسی مستقیم به operatingAccount دارد، نیازی به تنظیم loginAccount ندارید و مقدار پیش‌فرض آن operatingAccount است. با این حال، توصیه می‌کنیم loginAccount روی همان accountId و accountType مربوط به operatingAccount تنظیم کنید. این کار به جلوگیری از مشکلات در صورت تغییر مجموعه حساب‌هایی که کاربر می‌تواند به آنها دسترسی داشته باشد، کمک می‌کند.

productDestinationId

شناسه‌ی موجودیتی در operatingAccount که رویدادها را دریافت می‌کند.

برای رویدادهایی که به عنوان منبع داده اضافی ارسال می‌شوند، productDestinationId باید شناسه تبدیل Google Ads با type تنظیم شده روی WEBPAGE یا شناسه اندازه‌گیری یک جریان وب Google Analytics باشد. شما نمی‌توانید رویدادها را به عنوان منبع داده اضافی به یک برنامه Google Analytics iOS یا جریان برنامه Android ارسال کنید.

برای تبدیل‌های آفلاین یا تبدیل‌های پیشرفته برای سرنخ‌ها، productDestinationId باید شناسه یک اقدام تبدیل گوگل ادز با type تنظیم شده روی UPLOAD_CLICKS باشد.

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

آماده‌سازی داده‌های رویداد

داده‌های رویداد زیر را در نظر بگیرید. هر جدول مربوط به یک رویداد تبدیل است. هر رویداد تبدیل دارای یک مهر زمانی از رویداد، عمل تبدیل آن و مقدار تبدیل است.

هر رویداد ممکن است شناسه‌های تبلیغاتی مانند gclid یا شناسه‌های کاربری مانند آدرس‌های ایمیل، شماره تلفن‌ها و اطلاعات آدرس داشته باشد. یک رویداد همچنین می‌تواند موارد زیر را داشته باشد:

داده‌های رویداد به شرح زیر است:

رویداد ۱

رویداد شماره ۱
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name John
family_name Smith-Jones
region_code us
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
اقلام سبد خرید
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

رویداد ۲

رویداد شماره ۲
conversion_time June 10, 2025 11:42:33PM America/New_York
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency eur
gclid GCLID_2
emails

zoe@EXAMPLE.COM

cloudy.sanfrancisco@gmail.com

given_name zoë
family_name pérez
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
اقلام سبد خرید
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

قالب‌بندی داده‌ها

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

رویداد ۱

رویداد شماره ۱
conversion_time 2025-06-10T15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name john
family_name smith-jones
region_code US
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
اقلام سبد خرید
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

رویداد ۲

رویداد شماره ۲
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency EUR
gclid GCLID_2
emails

zoe@example.com

cloudysanfrancisco@gmail.com

given_name zoë
family_name pérez
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
اقلام سبد خرید
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

هش کردن و رمزگذاری داده‌ها

علاوه بر این، آدرس‌های ایمیل فرمت‌شده، نام‌های داده‌شده و نام‌های خانوادگی باید با استفاده از الگوریتم SHA-256 هش شده و با استفاده از کدگذاری hex یا Base64 کدگذاری شوند. در اینجا داده‌های رویداد پس از قالب‌بندی، هش کردن و کدگذاری با استفاده از کدگذاری hex آمده است:

رویداد ۱

رویداد شماره ۱
conversion_time 2025-06-10T15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 30.03
currency USD
gclid GCLID_1
emails
given_name 96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A
family_name DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081
region_code US
postal_code 94045
customer_type NEW
customer_value_bucket HIGH
client_id 1234567890.1761581763
user_id user_ABC12345
ad_unit_name Banner_01
event_name purchase
اقلام سبد خرید
item_id SKU_12345
item_name Stan and Friends Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 2.22
item_index 0
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 10.01
item_quantity 3

رویداد ۲

رویداد شماره ۲
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 42.02
currency EUR
gclid GCLID_2
emails

3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250

223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4

given_name 2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450
family_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076
customer_type RETURNING
client_id 9876543210.1761582117
user_id user_DEF9876
ad_unit_name Banner_02
event_name purchase
اقلام سبد خرید
item_id SKU_12346
item_name Google Grey Women's Tee
item_affiliation Google Merchandise Store
item_coupon SUMMER_FUN
item_discount 3.33
item_index 1
item_brand Google
item_category Apparel
item_category2 Adult
item_category3 Shirts
item_category4 Crew
item_category5 Short sleeve
item_list_id related_products
item_list_name Related Products
item_price 21.01
item_quantity 2

تبدیل داده‌ها به اشیاء Event

داده‌های قالب‌بندی و هش‌شده‌ی هر رویداد را به یک Event تبدیل کنید. فیلدهای زیر را مطابق دستورالعمل پر کنید:

  1. eventTimestamp روی زمان وقوع رویداد تنظیم کنید.

    رویدادهای گوگل آنالیتیکس باید در ۷۲ ساعت گذشته دارای eventTimestamp باشند.

  2. فیلدهای مورد نیاز برای مورد استفاده خود را تنظیم کنید.

    مورد استفاده شناسه‌ها transactionId eventSource
    تبدیل‌های آفلاین یا تبدیل‌های بهبود یافته برای سرنخ‌ها الزامی . حداقل یکی از موارد زیر را تنظیم کنید:
    • adIdentifiers که حداقل یکی از gclid ، gbraid ، wbraid یا sessionAttributes در آنها تنظیم شده باشد
    • userData
    		 اختیاری الزامی . روی یکی از مقادیر شمارشی برای EventSource تنظیم شود.
    رویدادهایی که به عنوان منبع داده اضافی به مقصد تبلیغات گوگل ارسال می‌شوند الزامی . حداقل یکی از موارد زیر را تنظیم کنید:
    • adIdentifiers که حداقل یکی از مجموعه‌های gclid ، gbraid یا wbraid را داشته باشند
    • userData
    		 مورد نیاز اختیاری. در صورت تنظیم، باید WEB باشد.
    رویدادهایی که به عنوان منبع داده اضافی به مقصد Google Analytics ارسال می‌شوند الزامی . حداقل یکی از موارد زیر را تنظیم کنید: مورد نیاز اختیاری. در صورت تنظیم، باید WEB باشد.

  3. هر فیلد دیگری را که مقداری برای رویداد دارید، پر کنید. برای مشاهده لیست کامل فیلدهای موجود، به مستندات مرجع Event مراجعه کنید.

اطلاعات گوگل آنالیتیکس را اضافه کنید

اگر مقاصد رویدادی که به عنوان منبع داده اضافی ارسال می‌شود شامل یک ویژگی Google Analytics است، فیلدهای زیر را همانطور که نشان داده شده است، پر کنید:

eventName

الزامی . نام رویداد گوگل آنالیتیکس.

transactionId

الزامی . شناسه منحصر به فرد برای رویداد.

حداقل یک شناسه

حداقل یکی از فیلدهای زیر باید تنظیم شود:

destinationReferences

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

اگر destinationReferences تنظیم نشده باشد یا چندین ورودی داشته باشد که به مقصدهای گوگل آنالیتیکس اشاره می‌کنند، رابط برنامه‌نویسی کاربردی مدیریت داده (Data Manager API) این رویداد را با خطای MULTIPLE_DESTINATIONS_FOR_GOOGLE_ANALYTICS_EVENT رد می‌کند.

userId

اختیاری. شناسه کاربری برای کاربر.

additionalEventParameters

اختیاری، اما توصیه می‌شود. این لیست را با هر پارامتر رویداد گوگل آنالیتیکس که در فیلدهای Event دیگر ثبت نشده‌اند، پر کنید. این پارامترها می‌توانند شامل پارامترهای پیشنهادی اضافی از رویداد purchase یا سایر پارامترهایی باشند که می‌خواهید ثبت کنید. از نام پارامتر گوگل آنالیتیکس برای parameterName نام EventParameter استفاده کنید.

برای مثال، اگر مالیات‌های مرتبط با یک تراکنش را دارید، یک ورودی به additionalEventParameters اضافه کنید که در آن parameterName برابر با tax و value برابر با هزینه مالیات تنظیم شده باشد.

ما توصیه نمی‌کنیم که برای پارامترهای رویداد Google Analytics، ورودی‌هایی برای transactionId ، currency یا value اضافه کنید. در عوض، transactionId ، currency و conversionValue Event را پر کنید، که بر هر ورودی در additionalEventParameters اولویت دارند.

اضافه کردن داده‌های سبد خرید برای رویدادهای خرید

فیلد cartData از Event را با اطلاعات مربوط به اقلام خریداری شده پر کنید. برای هر کالای خریداری شده، یک شیء Item به لیست items CartData اضافه کنید و فیلدهای زیر را همانطور که نشان داده شده است پر کنید:

itemId
الزامی . یک شناسه منحصر به فرد برای کالا.
unitPrice

الزامی . قیمت واحد بدون احتساب مالیات، هزینه ارسال و تخفیف‌های مربوط به رویداد (در سطح تراکنش).

اگر کالا تخفیف ویژه دارد، از قیمت واحد تخفیف‌دار استفاده کنید. برای مثال، اگر قیمت واحد یک کالا 27.67 و تخفیف واحد آن 6.66 باشد، unitPrice روی 21.01 تنظیم کنید.

quantity

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

additionalItemParameters

این لیست را با هر پارامتری که در سایر فیلدهای Item قرار نمی‌گیرد و در محدوده Item قرار نمی‌گیرد، پر کنید. برای parameterName از ItemParameter از نام پارامتر آیتم گوگل آنالیتیکس استفاده کنید.

برای مثال، اگر برند و دسته‌بندی یک کالا را دارید، یک ورودی به additionalItemParameters آن کالا اضافه کنید که parameterName روی item_brand تنظیم شده و value روی نام برند تنظیم شده باشد، و یک ورودی دیگر با parameterName روی item_category تنظیم شده و value آن روی دسته‌بندی کالا تنظیم شده باشد.

ما توصیه نمی‌کنیم که برای پارامترهای آیتم Google Analytics مانند quantity ، price یا item_id ورودی اضافه کنید. در عوض، itemId ، unitPrice و quantity مربوط به Item را که بر هر ورودی دیگری در additionalItemParameters اولویت دارند، پر کنید.

در اینجا یک Event نمونه برای داده‌های قالب‌بندی شده، هش شده و رمزگذاری شده از رویداد دوم، به همراه داده‌های اضافی برای گوگل آنالیتیکس، آورده شده است:

{
  "adIdentifiers": {
     "gclid": "GCLID_2"
  },
  "conversionValue": 42.02,
  "currency": "EUR",
  "eventTimestamp": "2025-06-10T23:42:33-05:00",
  "transactionId": "DEF999911111",
  "eventSource": "WEB",
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
      },
      {
        "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
      },
      {
        "address": {
          "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
          "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
          "regionCode": "PT",
          "postalCode": "1229-076"
        }
      }
    ],
  },
  "userProperties": {
    "customerType": "RETURNING"
  },
  "eventName": "purchase",
  "clientId": "9876543210.1761582117",
  "userId": "user_DEF9876",
  "additionalEventParameters": [
    {
      "parameterName": "ad_unit_name",
      "value": "Banner_02"
    }
  ],
  "cartData": {
    "transactionDiscount": 6.66,
    "items": [
      {
        "itemId": "SKU_12346",
        "quantity": 2,
        "unitPrice": 21.01,
        "additionalItemParameters": [
          {
            "parameterName": "item_name",
            "value": "Google Grey Women's Tee"
          },
          {
            "parameterName": "affiliation",
            "value": "Google Merchandise Store"
          },
          {
            "parameterName": "coupon",
            "value": "SUMMER_FUN"
          },
          {
            "parameterName": "discount",
            "value": "3.33"
          },
          {
            "parameterName": "index",
            "value": "1"
          },
          {
            "parameterName": "item_brand",
            "value": "Google"
          },
          {
            "parameterName": "item_category",
            "value": "Apparel"
          },
          {
            "parameterName": "item_category2",
            "value": "Adult"
          },
          {
            "parameterName": "item_category3",
            "value": "Shirts"
          },
          {
            "parameterName": "item_category4",
            "value": "Crew"
          },
          {
            "parameterName": "item_category5",
            "value": "Short sleeve"
          },
          {
            "parameterName": "item_list_id",
            "value": "related_products"
          },
          {
            "parameterName": "item_list_name",
            "value": "Related Products"
          }
        ]
      }
    ]
  }
}

ساخت بدنه درخواست

Destination و Events برای بدنه درخواست ترکیب کنید:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 30.03,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "NEW",
         "customerValueBucket": "HIGH"
       },
       "eventName": "purchase",
       "clientId": "1234567890.1761581763",
       "userId": "user_ABC12345",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_01"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12345",
             "quantity": 3,
             "unitPrice": 10.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Stan and Friends Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "2.22"
               },
               {
                 "parameterName": "index",
                 "value": "0"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]

       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 42.02,
       "currency": "EUR",
       "eventTimestamp": "2025-06-11T04:42:33Z",
       "transactionId": "DEF999911111",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "emailAddress": "3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250"
           },
           {
             "emailAddress": "223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4"
           },
           {
             "address": {
               "givenName": "2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450",
               "familyName": "6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F",
               "regionCode": "PT",
               "postalCode": "1229-076"
             }
           }
         ]
       },
       "userProperties": {
         "customerType": "RETURNING"
       },
       "eventName": "purchase",
       "clientId": "9876543210.1761582117",
       "userId": "user_DEF9876",
       "additionalEventParameters": [
         {
           "parameterName": "ad_unit_name",
           "value": "Banner_02"
         }
       ],
       "cartData": {
         "transactionDiscount": 6.66,
         "items": [
           {
             "itemId": "SKU_12346",
             "quantity": 2,
             "unitPrice": 21.01,
             "additionalItemParameters": [
               {
                 "parameterName": "item_name",
                 "value": "Google Grey Women's Tee"
               },
               {
                 "parameterName": "affiliation",
                 "value": "Google Merchandise Store"
               },
               {
                 "parameterName": "coupon",
                 "value": "SUMMER_FUN"
               },
               {
                 "parameterName": "discount",
                 "value": "3.33"
               },
               {
                 "parameterName": "index",
                 "value": "1"
               },
               {
                 "parameterName": "item_brand",
                 "value": "Google"
               },
               {
                 "parameterName": "item_category",
                 "value": "Apparel"
               },
               {
                 "parameterName": "item_category2",
                 "value": "Adult"
               },
               {
                 "parameterName": "item_category3",
                 "value": "Shirts"
               },
               {
                 "parameterName": "item_category4",
                 "value": "Crew"
               },
               {
                 "parameterName": "item_category5",
                 "value": "Short sleeve"
               },
               {
                 "parameterName": "item_list_id",
                 "value": "related_products"
               },
               {
                 "parameterName": "item_list_name",
                 "value": "Related Products"
               }
             ]
           }
         ]
       }
     }
  ],
  "validateOnly": true
}
  1. متغیرهای درون بدنه، مانند OPERATING_ACCOUNT_ID و PRODUCT_DESTINATION_ID را با مقادیر حساب و مقصد خود به‌روزرسانی کنید.
  2. برای اعتبارسنجی درخواست بدون اعمال تغییرات، validateOnly روی true تنظیم کنید. وقتی آماده اعمال تغییرات شدید، validateOnly روی false تنظیم کنید.
  3. توجه داشته باشید که این مثال از رمزگذاری استفاده نمی‌کند.

درخواست را ارسال کنید

  1. متن درخواست را با استفاده از دکمه کپی در سمت راست بالای نمونه کپی کنید.
  2. روی دکمه API در نوار ابزار کلیک کنید.
  3. متن درخواست کپی شده را در کادر Request body قرار دهید.
  4. روی دکمه‌ی اجرا کلیک کنید، مراحل احراز هویت را تکمیل کنید و پاسخ را بررسی کنید.

پاسخ‌های موفقیت

یک درخواست موفق، پاسخی را با یک شیء حاوی requestId برمی‌گرداند.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

requestId برگردانده شده را ثبت کنید تا بتوانید با پردازش هر مقصد در درخواست، عیب‌یابی را بازیابی کنید.

پاسخ‌های مربوط به شکست

یک درخواست ناموفق منجر به یک کد وضعیت پاسخ خطا مانند 400 Bad Request و پاسخی با جزئیات خطا می‌شود.

برای مثال، یک emailAddress که حاوی یک رشته متن ساده به جای یک مقدار کدگذاری شده هگز است، پاسخ زیر را تولید می‌کند:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

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

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

ارسال رویدادها برای چندین مقصد

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

برای مثال، اگر رویدادی برای اقدام تبدیل با شناسه 123456789 و رویداد دیگری برای اقدام تبدیل با شناسه 777111122 دارید، هر دو رویداد را در یک درخواست واحد با تنظیم reference هر Destination ارسال کنید. reference توسط کاربر تعریف می‌شود. تنها شرط این است که هر Destination یک reference منحصر به فرد داشته باشد. در اینجا لیست destinations اصلاح شده برای درخواست آمده است:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "PRODUCT_DESTINATION_ID",
      "reference": "destination_a"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "777111122",
      "reference": "destination_b"
    }
  ]

destinationReferences هر Event را طوری تنظیم کنید که آن را به یک یا چند مقصد خاص ارسال کند. برای مثال، در اینجا Event داریم که فقط برای اولین Destination است، بنابراین لیست destinationReferences آن فقط شامل reference اولین Destination است:

{
   "adIdentifiers": {
      "gclid": "GCLID_1"
   },
   "conversionValue": 1.99,
   "currency": "USD",
   "eventTimestamp": "2025-06-10T20:07:01Z",
   "transactionId": "ABC798654321",
   "eventSource": "WEB",
   "destinationReferences": [
      "destination_a"
   ]
}

فیلد destinationReferences یک لیست است، بنابراین می‌توانید چندین مقصد را برای یک رویداد مشخص کنید. اگر destinationReferences یک Event را تنظیم نکنید، رابط برنامه‌نویسی کاربردی (API) مدیریت داده، رویداد را به تمام مقاصد موجود در درخواست ارسال می‌کند.

اگر یک رویداد چندین مقصد داشته باشد، رابط برنامه‌نویسی کاربردی (API) مدیریت داده، فیلدهای مرتبط را به هر مقصد ارسال می‌کند. برای مثال، اگر یک رویداد یک مقصد Google Ads و یک مقصد Google Analytics داشته باشد، API هنگام ارسال رویداد به مقصد Google Analytics، فیلدهای Google Analytics مانند clientId یا eventName را شامل می‌شود و هنگام ارسال رویداد به مقصد Google Ads، فیلدهای Google Ads مانند customVariables را نیز شامل می‌شود.

مراحل بعدی

قبلی
مروری بر رویدادها