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

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

داده‌های رویداد یک منبع داده اضافی برای تبدیل‌های برچسب شما است تا سیگنال‌های تعامل تبلیغاتی را به حداکثر برساند و داده‌ها و عملکرد کلی شما را تقویت کند.

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

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

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

مقصدی را آماده کنید

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

    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  • accountId operatingAccount را روی شناسه حساب Google Ads تنظیم کنید که داده‌های رویداد را دریافت می‌کند. product operatingAccount باید GOOGLE_ADS باشد.

  • productDestinationId را روی شناسه کنش تبدیل رویدادها تنظیم کنید. اقدام تبدیل باید یک اقدام تبدیل Google Ads باشد که type روی WEBPAGE تنظیم شده است.

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

داده های رویداد را آماده کنید

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

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

در اینجا داده های اولین رویداد آمده است:

رویداد شماره 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name John
family_name Smith-Jones
region_code us
postal_code 94045

در اینجا داده های رویداد دوم آمده است:

رویداد شماره 2
conversion_time June 10, 2025 11:42:33PM America/New_York
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
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

داده ها را فرمت کنید

فیلدها را مطابق با راهنمای قالب بندی فرمت کنید. در اینجا داده های اولین رویداد پس از قالب بندی آمده است:

رویداد شماره 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name john
family_name smith-jones
region_code US
postal_code 94045

در اینجا داده های رویداد دوم پس از قالب بندی آمده است:

رویداد شماره 2
conversion_time 2025-06-10T23:42:33-05:00
conversion_action_id 123456789
transaction_id DEF999911111
conversion_value 3.25
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

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

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

رویداد شماره 1
conversion_time 2025-06-10 15:07:01-05:00
conversion_action_id 123456789
transaction_id ABC798654321
conversion_value 1.99
currency USD
gclid GCLID_1
emails
given_name 96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A
family_name DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081
region_code US
postal_code 94045

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

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

3E693CF7E5B67880BFF33B2D2626DADB7BF1D4BC737192E47CF8BAA89ACF2250

223EBDA6F6889B1494551BA902D9D381DAF2F642BAE055888E96343D53E9F9C4

given_name 2752B88686847FA5C86F47B94CE652B7B3F22A91C37617D451A4DB9AFA431450
family_name 6654977D57DDDD3C0329CA741B109EF6CD6430BEDD00008AAD213DF25683D77F
region_code PT
postal_code 1229-076

داده ها را به یک Event تبدیل کنید

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

  • event_timestamp : زمان وقوع رویداد.
  • transaction_id : شناسه منحصر به فرد رویداد.
  • event_source : منبع رویداد. اگر مشخص شده است، این باید WEB باشد.
  • ad_identifiers یا user_data : رویداد باید دارای شناسه آگهی یا داده های کاربر باشد. اگر هر دو را برای رویداد دارید، هر دو را بفرستید.

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

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

{
   "adIdentifiers": {
      "gclid": "GCLID_2"
   },
   "conversionValue": 3.25,
   "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"
            }
         }
      ]
   }
}

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

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

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "CONVERSION_ACTION_1_ID"
    }
  ],
  "encoding": "HEX",
  "events": [
     {
       "adIdentifiers": {
         "gclid": "GCLID_1"
       },
       "conversionValue": 1.99,
       "currency": "USD",
       "eventTimestamp": "2025-06-10T20:07:01Z",
       "transactionId": "ABC798654321",
       "eventSource": "WEB",
       "userData": {
         "userIdentifiers": [
           {
             "address": {
               "givenName": "96D9632F363564CC3032521409CF22A852F2032EEC099ED5967C0D000CEC607A",
               "familyName": "DB98D2607EFFFA28AFF66975868BF54C075ECA7157E35064DCE08E20B85B1081",
               "regionCode": "US",
               "postalCode": "94045"
             }
           }
         ]
       }
     },
     {
       "adIdentifiers": {
         "gclid": "GCLID_2"
       },
       "conversionValue": 3.25,
       "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"
             }
           }
         ]
       }
     }
  ],
  "validateOnly": true
}
  1. متغیرهای موجود در بدنه، مانند OPERATING_ACCOUNT_ID و CONVERSION_ACTION_1_ID را با مقادیر حساب و مقصد خود به‌روزرسانی کنید.
  2. برای تأیید اعتبار درخواست بدون اعمال تغییرات، validateOnly روی true تنظیم کنید. وقتی برای اعمال تغییرات آماده شدید، validateOnly روی false قرار دهید.
  3. توجه داشته باشید که این درخواست از رمزگذاری استفاده نمی کند.

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

  1. بدنه درخواست را با استفاده از دکمه کپی در سمت راست بالای نمونه کپی کنید.
  2. به صفحه events.ingest بروید.
  3. روی دکمه API در سمت راست کلیک کنید، سپس روی Try it! دکمه در بخش گسترش یافته
  4. بدنه درخواست کپی شده را در کادر بدنه درخواست جایگذاری کنید.
  5. روی دکمه Execute کلیک کنید، دستورات مجوز را تکمیل کنید و پاسخ را بررسی کنید.

پاسخ های موفقیت آمیز

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

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

پاسخ های شکست

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

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

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

email_address که هش نشده و فقط کدگذاری شده هگز است، پاسخ زیر را ایجاد می‌کند:

{
  "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": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "123456789"
      "reference": "conversion_action_1"
    },
    {
      "operatingAccount": {
        "product": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "777111122"
      "reference": "conversion_action_2"
    }
  ]

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

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

قسمت destination_references یک لیست است، بنابراین می توانید مقصدهای متعددی را برای یک رویداد مشخص کنید. اگر destination_references یک Event را تنظیم نکنید، API مدیر داده رویداد را به همه مقصدهای موجود در درخواست ارسال می‌کند.

مراحل بعدی