رهگیری رویداد ها

رهگیری رویداد ها

زبلاین یک API برای ردیابی رویدادهای سفارشی از طریق نقطهٔ پایانی /events ارائه می‌دهد که در ادامه توضیح داده شده است.

🚧 مطالعهٔ ضروری

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

چند الگوی رویداد سفارشی در اینجا آورده شده است تا به شما در شروع کار کمک کند.

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

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

قبل از مطالعه این بخش، مطمئن شوید که در مورد رویداد ها در بخش مقدمه اطلاعات کافی را دارید.

ردیابی رویدادهای سفارشی

نکات مهم:

• نام رویداد سفارشی باید کمتر از ۵۰ کاراکتر باشد.
• نام ویژگی‌های رویداد سفارشی نسبت به حروف بزرگ و کوچک حساس است و نباید بیش از ۵۰ کاراکتر باشد.
• مقدار ویژگی‌هایی که از نوع رشته (String) هستند نباید بیش از ۱۰۰۰ کاراکتر باشد.

انواع داده‌های مجاز برای ویژگی‌های رویداد:

ویژگی‌های رویداد سفارشی می‌توانند از انواع داده‌های زیر باشند:

• رشته (String)
• عددی (Number)
• بولی (Boolean)
• تاریخ (Date)
• آرایهٔ JSON (JSON Array)
• شیٔ JSON (JSON Object)

نکته: شیٔ JSON فقط می‌تواند شامل یکی از انواع داده‌های فوق باشد.

قراردادهای نام‌گذاری

• تمامی کلیدها باید به‌صورت حروف کوچک (lowercase) باشند.

• برای نام‌گذاری کلیدهایی که بیش از یک کلمه دارند، از زیرخط (_) استفاده کنید.

  • مثال: first_name، membership_level، favorite_color

محدودیت‌های تعداد ویژگی‌ها:

• شما می‌توانید حداکثر ۲۵ ویژگی از هر نوع داده برای یک رویداد سفارشی ایجاد کنید.

تعریف نوع داده:

• اولین داده‌ای که به زبلاین ارسال می‌شود، نوع دادهٔ ویژگی رویداد را تعیین می‌کند.
• بنابراین، انواع داده‌ها باید با مقادیری که می‌خواهید برای ویژگی ذخیره کنید، سازگار باشند.
• اگر نوع داده بعداً تغییر کند، جریان داده‌های ویژگی رویداد سفارشی به داشبورد زبلاین متوقف خواهد شد.

مستندات API رویدادها در زبلاین

/events

متد: POST

نمونه درخواست cURL

curl --location --globoff 'https://api.zebline.com/v1/accounts/LICENSE_CODE/events' \
    --header 'Authorization: Bearer ACCESS_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
      "userId": "TX1",
      "eventName": "page_view",
      "eventTime": "2024-01-01T00:00:00.000000",
      "eventData": {
        "page_url": "https://example.com/home",
        "device": "mobile"
      }
    }'

توجه

لطفاً اطمینان حاصل کنید که:

• مقدار LICENSE_CODE را با کد لایسنس زبلاین خود جایگزین کنید.
• مقدار ACCESS_TOKEN را با کلید API زبلاین خود جایگزین کنید.

احراز هویت: استفاده از Bearer Authentication Scheme برای احراز هویت ضروری است.

محدودیت نرخ فراخوانی API: حداکثر ۵۰۰۰ درخواست در دقیقه مجاز است.

نکات مهم:

• شما نمی‌توانید از طریق API زبلاین، رویدادهای سیستمی ایجاد کنید.
• لیست رویدادهای سیستمی که به‌صورت خودکار توسط زبلاین ردیابی می‌شوند در مستندات رسمی موجود است.
• لطفاً از ایجاد رویدادهای سفارشی با نام مشابه رویدادهای سیستمی خودداری کنید تا از بروز ابهام جلوگیری شود.

هنگام ارسال درخواست رویداد، فیلدهای زیر الزامی هستند:

• eventName: نام رویداد
• eventTime: زمان رویداد
• userId: شناسه کاربر (یا anonymousId در صورت ارسال ترافیک ناشناس)
• eventData: اطلاعات مرتبط با رویداد

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

• اگر می‌خواهید رویداد را برای کاربران شناخته‌شده ارسال کنید، باید مقدار userId را ارسال کنید.
• اگر می‌خواهید رویداد را برای کاربران ناشناس ارسال کنید، باید مقدار anonymousId را ارسال کنید.

هدرها (Headers)

نام	توضیحات
x-request-id:{HEX_STRING}	مقدار {HEX_STRING} را با یک رشتهٔ هگزادسیمال تصادفی و یکتا جایگزین کنید.

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

• اگر تلاش مجدد برای ارسال یک رویداد انجام شود، این تگ از تکثیر رویدادهای تکراری در بازهٔ ۴ ساعته جلوگیری می‌کند.
• رویدادهایی که با همان شناسه (ID) مجدداً ارسال شوند، در صورتی که درخواست HTTP اولیه موفق بوده باشد، پردازش مجدد نخواهند شد.

پارامترها

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

پارامتر	نوع	توضیحات	الزامی
userId	String	شناسه کاربر شناخته‌شده. یکی از userId یا anonymousId الزامی است. شناسه کاربر را می‌توان در صفحهٔ پروفایل کاربر در داشبورد زبلاین یافت. محدودیت: حداکثر ۱۰۰ کاراکتر.	بله
anonymousId	String	شناسه کاربر ناشناس. یکی از userId یا anonymousId الزامی است. در صورت ارسال هر دو، anonymousId نادیده گرفته می‌شود. محدودیت: حداکثر ۱۰۰ کاراکتر. توجه: ارسال هر دو مقدار userId و anonymousId باعث ادغام کاربر ناشناس با کاربر شناخته‌شده نخواهد شد.	بله
eventName	String	نام رویداد.	بله
eventTime	String	تاریخ و زمان وقوع رویداد در فرمت ISO: yyyy-MM-ddTHH:mm:ss±hhmm	بله
eventData	String	ویژگی‌های رویداد به‌صورت جفت کلید-مقدار. به عنوان مثال: { "Product ID": 1337, "Category": "Fragrance" }. داده‌های مجاز برای ویژگی‌های سفارشی شامل: String، Number، Boolean، Date، JSON Array، JSON Object. توجه: شیٔ JSON فقط می‌تواند شامل یکی از این انواع داده‌ها باشد.	بله

پاسخ API

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

{
    "response": {
        "status": "queued",
        "trackID": "476d2705-0deb-45c7-8f18-8be0b289f42a"
    }
}

توضیحات فیلدهای پاسخ:

فیلد	نوع	توضیحات
status	String	وضعیت پردازش درخواست. مقدار queued به این معنی است که درخواست در صف پردازش قرار گرفته است.
trackID	String	شناسه یکتای پیگیری درخواست، که می‌توان از آن برای بررسی وضعیت درخواست استفاده کرد.

برای بررسی وضعیت درخواست‌های پردازش‌شده، می‌توان از مقدار trackID استفاده کرد.

کدهای وضعیت خطا

خطاها با استفاده از استاندارد HTTP Error Code نمایش داده می‌شوند. پاسخ‌ها همیشه در قالب JSON ارائه می‌شوند.

کد	معنی	نحوهٔ رفع مشکل
400	منبع/پارامترهای نامعتبر	۱. بررسی کنید که کد لایسنس را به‌درستی در مسیر درخواست API وارد کرده باشید. بررسی کنید که در حال دسترسی به منبع معتبری مانند /users، /events، /transaction یا /survey/response/ هستید. در صورت ادامهٔ مشکل، با پشتیبانی زبلاین تماس بگیرید.
401	احراز هویت نامعتبر / دسترسی غیرمجاز	۱. با پشتیبانی زبلاین تماس بگیرید و کلید API مورد استفاده را ارائه دهید. در تنظیمات حساب، بررسی کنید که مدیر حساب مجوزهای کافی برای مدیریت و به‌روزرسانی داده‌ها را دارد. اگر مدیر حساب حذف شده است، کلید API معتبر را در تمامی درخواست‌های فعال جایگزین کنید.
404	آدرس نامعتبر	۱. بررسی کنید که از هاست صحیح (مطابق با مرکز داده زبلاین شما) به‌عنوان آدرس والد استفاده کرده‌اید. در صورت ادامهٔ مشکل، با پشتیبانی زبلاین تماس بگیرید.

در صورت داشتن سؤالات بیشتر، لطفاً با پشتیبانی زبلاین در ارتباط باشید.