پارامترهای کالبک | متریکس Metrix

نمای کلی: کال‌بک‌ها در متریکس

کال‌بک‌ها (Callbacks) درخواست‌های HTTP هستند که متریکس در زمان واقعی (بلادرنگ) و هنگام وقوع ایونت های خاص (نصب، نصب مجدد، تشخیص تقلب، ایونت های سفارشی و غیره) به سرور شما ارسال می‌کند. این درخواست‌ها به شما امکان می‌دهند تا داده‌های متریکس را با سیستم‌های داخلی، پلتفرم‌های تحلیلی یا انبار داده خود، بدون نیاز به نظرسنجی مداوم، همگام‌سازی کنید.

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

همگام‌سازی بی‌درنگ داده‌ها: بلافاصله داده‌های نصب و ایونت را در سیستم‌های بک‌اند خود دریافت کنید.
یکپارچه‌سازی اتریبیوشن : داده‌های تبدیل را به شبکه‌های تبلیغاتی یا پلتفرم‌های تحلیلی خود ارسال کنید.
گردش کارهای سفارشی: منطق کسب و کار خود را بر اساس اقدامات کاربر ردیابی شده در متریکس فعال کنید.
یکپارچه‌سازی هوش تجاری (BI): داده‌ها را مستقیماً به انبار داده یا ابزارهای تحلیلی خود ارسال کنید.

راه‌اندازی یکپارچه‌سازی برای پارتنر

برای پیوستن به شبکه پارتنری یکپارچه ما و بهره‌مندی از راه‌اندازی یکپارچه‌سازی پویا، الزامات زیر را تکمیل کنید. پس از ارسال، تیم یکپارچه‌سازی ما تنظیمات شما را در داشبورد متریکس پیکربندی خواهد کرد.

اطلاعات راه‌اندازی مورد نیاز

توضیحات شرکت — یک توضیح 3-4 کلمه‌ای از شرکت و خدمات خود ارائه دهید. این توضیحات در صفحه پارتنر و داشبورد ما نمایش داده می‌شود.
اطلاعات تماس — مشخص کردن تماس فنی برای پیکربندی کال‌بک و عیب‌یابی.
نقطه پایانی کال‌بک (Callback Endpoint) — آدرس URL نقطه پایانی HTTPS شما که متریکس درخواست‌های کال‌بک را به آن ارسال می‌کند.
شناسه‌های دستگاه (Device IDs) — مشخص کنید کدام شناسه‌های دستگاه باید گنجانده شوند:
- {android_id} — شناسه دستگاه اندروید
- {gps_adid} — شناسه تبلیغاتی خدمات گوگل پلی (Google Play Services Advertising ID)
پارامترهای سفارشی (Custom Parameters) — اگر هنگام ردیابی کلیک، شناسه‌های کلیک (Click IDs) یا پارامترهای سفارشی را ارسال می‌کنید، نام ماکروها را (مانند {click_id}، {campaign_id}) مشخص کنید تا در کال‌بک‌ها بازگردانده شوند.
پارامترهای کال‌بک (Callback Parameters) — پارامترهایی را که در کال‌بک‌های خود نیاز دارید، تعریف کنید (به مرجع پارامترها در ادامه مراجعه کنید).

آدرس‌های URL کال‌بک پویا

شما می‌توانید آدرس‌های URL کال‌بک را به صورت پویا به لینک‌های ردیابی با استفاده از پارامتر install_callback اضافه کنید:


https://tracker.metrix.ir/link/bdjulq?install_callback=https://callbacks.yourserver.com/path?install_data={tracker_code}&{campaign_name}

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

مرجع پارامترهای کال‌بک

پارامترهای موجود

جدول زیر تمام پارامترهایی را فهرست می‌کند که می‌توانند در URLهای کال‌بک گنجانده شوند. برای گنجاندن این مقادیر، از فرمت ماکرو {parameter_name} در URL کال‌بک خود استفاده کنید. ستون‌های “نوع کال‌بک” نشان می‌دهند که کدام یک از انواع ایونت از هر پارامتر پشتیبانی می‌کند.

راهنما:

✔ = پارامتر برای این نوع کال‌بک موجود است
✖ = پارامتر برای این نوع کال‌بک موجود نیست

در ادامه، مرجع جامع پارامترها آورده شده است:

پارامتر	نوع	توضیحات	مثال	نصب	نصب مجدد	حذف	تقلب	ایونت	کلیک
`tracker_code`	String	شناسه ردیاب	`bdjulq`	✔	✔	✔	✔	✖	✔
`network_name`	String	نام شبکه تبلیغاتی	`AdNetwork1`	✔	✔	✔	✔	✔	✔
`campaign_name`	String	نام کمپین	`Black Friday`	✔	✔	✔	✔	✔	✔
`adgroup_name`	String	نام گروه تبلیغاتی	`Video Banner`	✔	✔	✔	✔	✔	✔
`creative_name`	String	نام خلاقانه (تبلیغ)	`Product Features`	✔	✔	✔	✔	✔	✔
`sub_id`	String	Sub-ID	`83407c9a-392d-4f6b-b689-eadfe557ff18`, `abcdefg`	✔	✔	✔	✔	✔	✔
`action_name`	String	نوع اقدام (مثلاً، install, event, click, fraud)	`fraud`	✔	✔	✔	✔	✔	✔
`reinstalled`	Boolean	نشان می‌دهد که آیا نصب مجدد است یا خیر	`true`, `false`	✔	✔	✖	✖	✖	✖
`rejection_reason`	String	دلیل رد شدن تقلب	`anonymousIP`, `tooManyEngagements`, `clickInjection`	✖	✖	✖	✔	✖	✖
`event_slug`	String	شناسه ایونت	`uimgx`	✖	✖	✖	✖	✔	✖
`app_name`	String	نام پکیج اپلیکیشن	`com.example.test`	✔	✔	✔	✔	✔	✖
`app_version`	String	ورژن اپلیکیشن	`1.1.2.Beta`	✔	✔	✔	✔	✔	✖
`device_name`	String	مدل دستگاه	`sm-a505f`	✔	✔	✔	✔	✔	✖
`device_brand`	String	برند دستگاه	`xiaomi`	✔	✔	✔	✔	✔	✖
`device_manufacturer`	String	سازنده دستگاه	`xiaomi`	✔	✔	✔	✔	✔	✖
`android_id`	String	شناسه دستگاه اندروید	`b9da30111528c740`	✔	✔	✔	✔	✔	✖
`gps_adid`	String	شناسه تبلیغاتی گوگل	`38400000-8cf0-11bd-b23e-10b96e40000d`	✔	✔	✔	✔	✔	✖
`ip_address`	String	آدرس IP کاربر	`91.251.150.188`	✔	✔	✔	✔	✔	✔
`user_agent`	String	رشته User Agent	`Dalvik/2.1.0 (Linux; U; Android 10; JSN-L22 Build/HONORJSN-L22)`	✔	✔	✔	✔	✔	✔
`metrix_user_id`	String	شناسه کاربر متریکس	`c0bcf71e-a027-4cfa-974a-e90e040e5c3a`	✔	✔	✔	✔	✔	✔
`created_at`	Timestamp	زمان ایجاد (بر حسب میلی‌ثانیه)	`1403674212`	✔	✔	✔	✔	✔	✖
`clicked_at`	Timestamp	زمان کلیک (بر حسب میلی‌ثانیه)	`1403568849`	✔	✔	✔	✔	✖	✔
`installed_at`	Timestamp	زمان نصب (بر حسب میلی‌ثانیه)	`1404214634`	✔	✔	✔	✔	✔	✖
`city`	String	شهر کاربر	`Tehran`	✔	✔	✔	✔	✔	✔
`country`	String	کشور کاربر	`IRN`	✔	✔	✔	✔	✔	✔

نکات مربوط به فرمت پارامترها

حساسیت به حروف بزرگ و کوچک (Case Sensitivity): متریکس از نام پارامترهای camelCase و snake_case پشتیبانی می‌کند. می‌توانید از clicked_at یا clickedAt در URL کال‌بک خود استفاده کنید.
پارامترهای سفارشی: می‌توانید پارامترهای سفارشی را هنگام ردیابی کلیک ارسال کنید و با استفاده از همان فرمت مکان‌نما، آن‌ها را در کال‌بک‌ها درخواست کنید.
داده‌های سفارشی SDK: داده‌هایی که از طریق ویژگی‌های سفارشی SDK تنظیم می‌شوند نیز می‌توانند در کال‌بک‌ها گنجانده شوند.

ساختار URL کال‌بک

URLهای کال‌بک از فرمت استاندارد پارامترهای کوئری HTTP GET پیروی می‌کنند. در اینجا یک نمونه از کال‌بک نصب آورده شده است:


http://callbacks.myserver.com/path?clicked_at={clicked_at}&tracker_code={tracker_code}&ip_address={ip_address}

بهترین روش‌ها:

برای امنیت از نقاط پایانی HTTPS (نه HTTP) استفاده کنید.
فقط پارامترهایی را که نیاز دارید (تا طول URL به حداقل برسد) شامل کنید.
اطمینان حاصل کنید که نقطه پایانی شما می‌تواند پارامترهای رشته کوئری را مدیریت کند.
قبل از شروع به کار، URL کال‌بک خود را تست کنید.
برای تحویل‌های ناموفق، منطق تلاش مجدد (retry logic) را در سرور خود پیاده‌سازی کنید.

ویژگی‌های ایونت در کال‌بک‌ها

دسترسی به ویژگی‌های ایونت سفارشی

هنگام ردیابی ایونت های سفارشی، می‌توانید مقادیر ویژگی‌های ایونت را در URLهای کال‌بک خود بگنجانید. برای دریافت یک ویژگی ایونت :

از نام دقیق کلید ویژگی که در شمای ایونت خود تعریف کرده‌اید استفاده کنید.
آن را در کروشه به عنوان مکان‌نما قرار دهید: {attribute_key}
آن را در URL کال‌بک خود بگنجانید.

مثال: اگر ایونت شما دارای یک ویژگی سفارشی product_id است، می‌توانید آن را به این صورت دریافت کنید:


https://callbacks.yourserver.com/event?event_id={event_slug}&product_id={product_id}&timestamp={created_at}

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

برای ایونت های درآمدزا، از مکان‌نمای ویژه {_revenue} برای ثبت میزان تراکنش استفاده کنید:


https://callbacks.yourserver.com/purchase?event_slug={event_slug}&amount={_revenue}&currency=USD&user_id={metrix_user_id}

مکان‌نمای {_revenue} مقدار درآمد را با فرمت مشخص شده هنگام ثبت ایونت بازمی‌گرداند.

نمونه‌های کامل کال‌بک

کال‌بک نصب با داده‌های اتریبیوشن


https://callbacks.yourserver.com/install?
  tracker_code={tracker_code}&
  campaign_name={campaign_name}&
  network_name={network_name}&
  created_at={created_at}&
  ip_address={ip_address}&
  country={country}&
  metrix_user_id={metrix_user_id}

کال‌بک ایونت با ویژگی‌های سفارشی


https://callbacks.yourserver.com/event?
  event_slug={event_slug}&
  product_id={product_id}&
  category={category}&
  price={price}&
  quantity={quantity}&
  user_id={metrix_user_id}&
  timestamp={created_at}

کال‌بک ایونت درآمدی


https://callbacks.yourserver.com/purchase?
  event_slug={event_slug}&
  order_id={order_id}&
  amount={_revenue}&
  product_ids={product_ids}&
  user_id={metrix_user_id}&
  timestamp={installed_at}

کال‌بک تشخیص تقلب


https://callbacks.yourserver.com/fraud?
  action_name={action_name}&
  rejection_reason={rejection_reason}&
  tracker_code={tracker_code}&
  device_id={android_id}&
  timestamp={created_at}

مهم: اطمینان حاصل کنید که تمام کلیدهای ویژگی دقیقاً با آنچه در پیکربندی ایونت متریکس شما تعریف شده‌اند مطابقت دارند. نام‌های نامطابق منجر به مقادیر خالی در کال‌بک می‌شوند.