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

نمای کلی

متریکس یک برنامه یکپارچه‌سازی جامع برای شبکه‌های تبلیغاتی، پلتفرم‌های اتریبیوشن و پارتنری فناوری ارائه می‌دهد که می‌خواهند داده‌های نصب برنامه، داده‌های ایونت و اطلاعات کاربر را به صورت بلادرنگ به سیستم‌های خارجی ارسال کنند. این راهنما شما را با فرآیند یکپارچه‌سازی، الزامات فنی و بهترین شیوه‌ها آشنا می‌کند.

چه کسانی باید از این راهنما استفاده کنند؟

• شبکه‌های تبلیغاتی — برای ارسال داده‌های تبدیل به پلتفرم خود
• پلتفرم‌های اتریبیوشن — برای دریافت کال‌بک‌های نصب و ایونت
• پلتفرم‌های تحلیل داده — برای جمع‌آوری ایونت های خام جهت تحلیل
• سیستم‌های CRM — برای همگام‌سازی خودکار داده‌های کاربر
• ابزارهای هوش تجاری (BI) — برای یکپارچه‌سازی بلادرنگ انبار داده
• ارائه‌دهندگان خدمات شخص ثالث — برای یکپارچه‌سازی با متریکس جهت بهبود خدمات خود

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

گام 1: درخواست همکاری

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

گام 2: الزامات فنی

تیم یکپارچه‌سازی ما با شما همکاری خواهد کرد تا موارد زیر را تعریف کند:

1. نقطه پایانی کال‌بک (Callback Endpoints) — URL(های) HTTPS شما که متریکس داده‌ها را به آن ارسال می‌کند.
2. پارامترهای مورد نیاز — فیلدهای داده خاصی که شما نیاز دارید.
3. احراز هویت — کلیدهای API، فهرست سفید IP، یا سایر اقدامات امنیتی.
4. فرمت — JSON، پارامترهای کوئری URL، یا فرمت سفارشی.
5. روش تحویل — بلادرنگ، دسته‌ای، یا ترکیبی.

گام 3: پیکربندی و تست

پس از تعریف الزامات:

1. تیم ما یکپارچه‌سازی شما را در داشبورد متریکس پیکربندی می‌کند.
2. اعتبارنامه‌های تست و مستندات را دریافت می‌کنید.
3. فاز تست با ردیاب‌های مرحله‌بندی/تست آغاز می‌شود.
4. اعتبار سنجی دقت و کامل بودن داده‌ها.
5. استقرار و نظارت بر تولید.

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

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

1. توضیحات شرکت

یک توضیح 3-4 کلمه‌ای از شرکت و خدمات خود ارائه دهید. این توضیحات در موارد زیر ظاهر می‌شود:

• صفحه لیست پارتنری متریکس (عمومی)
• داشبورد متریکس (داخلی)
• مستندات یکپارچه‌سازی

مثال: “پلتفرم پیشرو اتریبیوشن بلادرنگ”

2. شناسه‌های دستگاه موبایل

مشخص کنید که سیستم شما به کدام شناسه‌های دستگاه نیاز دارد. متریکس می‌تواند موارد زیر را ارسال کند:

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

3. پارامترهای سفارشی

اگر در مرحله کلیک، شناسه‌های کلیک (Click IDs) یا پارامترهای سفارشی را ارسال می‌کنید، نام ماکروها را ارائه دهید:

این پارامترها در کال‌بک‌ها بازگردانده می‌شوند تا بتوانید تبدیل‌ها را با کلیک‌های اصلی مطابقت دهید.

پیکربندی پست‌بک و کال‌بک

درک کال‌بک در مقابل پست‌بک

در اکوسیستم متریکس:

• کال‌بک‌ها (Callbacks) — درخواست‌های HTTP بلادرنگ که متریکس به نقطه پایانی شما ارسال می‌کند (جریان داده از متریکس ← شما)
• پست‌بک‌ها (Postbacks) — داده‌های تاریخی که از طریق API یا خروجی انبوه ارسال می‌شوند (در زمینه پارتنر به طور متناوب با کال‌بک‌ها استفاده می‌شوند)

پیکربندی URL اصلی پست‌بک

نقطه پایانی HTTPS اصلی خود را که متریکس داده‌ها را به آن ارسال می‌کند، ارائه دهید. URL باید:

• فقط از HTTPS (رمزگذاری شده) استفاده کند.
• به صورت 24/7 در دسترس باشد (نظارت/هشدار).
• ظرفیت کافی برای حجم مورد انتظار شما داشته باشد.
• از پارامترهای استاندارد HTTP GET پشتیبانی کند.
• در صورت موفقیت، کد وضعیت HTTP 2xx را برگرداند.
• تلاش‌های مجدد را به طور صحیح مدیریت کند.

نمونه URLهای پست‌بک:

https://callbacks.yourcompany.com/metrix/install
https://api.yourcompany.com/v1/conversions/install
https://events.yourcompany.com/install?api_key=YOUR_KEY

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

متریکس می‌تواند این پارامترها را در تمام کال‌بک‌ها گنجانده باشد. انتخاب کنید که کدام یک را نیاز دارید:

داده‌های اتریبیوشن و کمپین

• {tracker_code} — شناسه منحصر به فرد ردیاب
• {network_name} — نام شبکه تبلیغاتی
• {campaign_name} — نام کمپین
• {adgroup_name} — نام گروه تبلیغاتی
• {creative_name} — نام خلاقانه/تبلیغ
• {sub_id} — Sub-ID برای ردیابی سفارشی

اطلاعات دستگاه و کاربر

• {android_id} — شناسه دستگاه اندروید
• {gps_adid} — Google Advertising ID
• {device_name} — نام مدل دستگاه
• {device_brand} — سازنده دستگاه
• {device_manufacturer} — OEM دستگاه
• {ip_address} — آدرس IP کاربر
• {user_agent} — رشته User Agent
• {metrix_user_id} — شناسه کاربر ناشناس متریکس

داده‌های موقعیت جغرافیایی

• {country} — کشور کاربر (کد 3 حرفی ISO)
• {city} — شهر کاربر
• {region} — منطقه/استان کاربر

داده‌های زمان‌بندی

• {created_at} — زمان ایجاد ایونت (Unix ms)
• {clicked_at} — زمان کلیک (Unix ms)
• {installed_at} — زمان نصب (Unix ms)

اطلاعات برنامه

• {app_name} — نام پکیج برنامه
• {app_version} — نسخه برنامه

اطلاعات عملیات

• {action_name} — نوع عملیات (نصب، ایونت ، تقلب، کلیک)
• {rejection_reason} — دلیل رد شدن تقلب (در صورت لزوم)
• {event_slug} — شناسه ایونت (برای کال‌بک‌های ایونت )

ساخت URL پست‌بک شما

فقط پارامترهایی را که نیاز دارید در URL خود وارد کنید. متریکس مقادیر واقعی را در زمان کال‌بک جایگزین خواهد کرد:

نمونه پست‌بک نصب:

https://callbacks.yourcompany.com/install?
  tracker_code={tracker_code}&
  network_name={network_name}&
  campaign_name={campaign_name}&
  country={country}&
  installed_at={installed_at}&
  gps_adid={gps_adid}&
  ip_address={ip_address}&
  metrix_user_id={metrix_user_id}

نمونه پست‌بک ایونت :

https://callbacks.yourcompany.com/event?
  event_slug={event_slug}&
  action_name={action_name}&
  tracker_code={tracker_code}&
  metrix_user_id={metrix_user_id}&
  created_at={created_at}

نمونه پست‌بک تشخیص تقلب:

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

پارامترهای ایونت و رد شدن

پست‌بک ایونت ها

برای کال‌بک‌های در سطح ایونت (خرید، ثبت‌نام و غیره):

• از {action_name} برای شناسایی نوع عملیات استفاده کنید.
• از {event_slug} برای شناسایی ایونت خاص استفاده کنید.
• هر ویژگی ایونت سفارشی را وارد کنید (به مرجع پارامترهای کال‌بک مراجعه کنید).

مثال:

https://callbacks.yourcompany.com/event?
  action_name=purchase&
  event_slug={event_slug}&
  value={_revenue}

نصب‌های رد شده (تشخیص تقلب)

هنگامی که متریکس نصب‌های تقلبی را شناسایی می‌کند:

• {rejection_reason} حاوی دلیل تقلب است.
• مقادیر ممکن: anonymousIP، tooManyEngagements، clickInjection، deviceSpoof، emulator.
• این کال‌بک‌ها به شما کمک می‌کنند تا تقلب را شناسایی و از آن جلوگیری کنید.

مثال:

https://callbacks.yourcompany.com/fraud?
  action_name={action_name}&
  rejection_reason={rejection_reason}&
  tracker_code={tracker_code}&
  created_at={created_at}

URLهای کال‌بک پویا

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

نحوه عملکرد

پارامتر install_callback را به URL ردیاب خود اضافه کنید:

https://tracker.metrix.ir/link/bdjulq?install_callback=https://your-callback.com/install?source={network_name}&campaign={campaign_name}

هنگامی که نصبی روی این ردیاب رخ می‌دهد:

1. متریکس نصب را پردازش می‌کند.
2. پارامترها در URL کال‌بک جایگزین می‌شوند.
3. کال‌بک بلادرنگ به نقطه پایانی مشخص شده شما ارسال می‌شود.

مزایا

• پیکربندی به ازای هر ردیاب — کال‌بک‌های مختلف برای کمپین‌های مختلف.
• عدم نیاز به پیکربندی اولیه — به صورت پویا در زمان ایجاد لینک تنظیم می‌شود.
• مسیریابی انعطاف‌پذیر — ارسال داده‌ها به سیستم‌های مختلف بر اساس منبع.
• تست A/B — ارسال به نقاط پایانی جایگزین برای تست.

نمونه موارد استفاده

مسیردهی داده‌ها به تیم‌های مختلف:

https://tracker.metrix.ir/link/abc123?
install_callback=https://sales-team.company.com/install?
  campaign={campaign_name}&lead={metrix_user_id}

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

https://tracker.metrix.ir/link/xyz789?
install_callback=https://primary-api.company.com/install&
install_callback_secondary=https://backup-api.company.com/install

شامل پارامترهای سفارشی:

https://tracker.metrix.ir/link/def456?
install_callback=https://crm.company.com/install?
  user_id={metrix_user_id}&
  custom_id={click_id}&
  source={network_name}

نظارت و پشتیبانی

معیارهای کلیدی برای نظارت

• نرخ موفقیت کال‌بک — درصد کال‌بک‌ها با پاسخ 2xx
• تأخیر کال‌بک — زمان از ایونت تا دریافت کال‌بک
• کامل بودن داده‌ها — درصد فیلدهای به درستی پر شده
• نرخ تلاش مجدد — تعداد دفعات تلاش مجدد
• ردیابی حجم — کال‌بک‌های کل در مقابل حجم مورد انتظار

عیب‌یابی

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

1. همیشه از HTTPS استفاده کنید — تمام کال‌بک‌ها باید رمزگذاری شوند.
2. ایده‌آل‌سازی را پیاده‌سازی کنید — کال‌بک‌های تکراری را به طور صحیح مدیریت کنید.
3. زمان‌بندی‌های مناسب را تنظیم کنید — ظرف 5-10 ثانیه پاسخ دهید.
4. همه چیز را ثبت کنید — برای اشکال‌زدایی سوابق حسابرسی را حفظ کنید.
5. کیفیت داده‌ها را نظارت کنید — دقت داده‌های دریافتی را تأیید کنید.
6. تلاش‌های مجدد را مدیریت کنید — بازه زمانی افزایشی را پیاده‌سازی کنید.
7. API خود را مستند کنید — پارامترها و پاسخ‌ها را به وضوح تعریف کنید.
8. به طور کامل تست کنید — قبل از تولید، در مرحله‌بندی تست کنید.
9. تغییرات را اطلاع دهید — تیم متریکس را از تغییرات نقطه پایانی مطلع کنید.
10. برای مقیاس‌پذیری برنامه‌ریزی کنید — برای 10 برابر حجم فعلی طراحی کنید.