فعالسازی On-Site Messaging (مختص سرویس اتومیشن)

نمای کلی

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

الزامات کلیدی

• شناسایی کاربر: کاربران باید با استفاده از authorizeUser() شناسایی شوند تا بتوانند پیام‌های درون‌سایتی دریافت کنند.
• شناسه کاربر اتوماسیون: SDK برای کاربران شناسایی‌شده یک automationUserId دریافت می‌کند تا پیام‌های هدفمند را بارگذاری کند.
• کاربران ناشناس: کاربران ناشناس از طریق این یکپارچه‌سازی پیام‌های درون‌سایتی دریافت نمی‌کنند.

شروع سریع

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

import { init, authorizeUser } from '@metrixorg/websdk';
 
// مرحله 1: SDK را با فعال‌سازی پیام‌رسانی درون‌سایتی مقداردهی اولیه کنید
init('APP_ID', 'API_KEY', {
  onSiteMessaging: {
    enabled: true,  // Enable on-site messaging
  },
});
 
// مرحله 2: کاربر را شناسایی کنید
authorizeUser('CUSTOM_USER_ID');

پیکربندی

فعال‌سازی پیام‌رسانی درون‌سایتی

در پیکربندی SDK، مقدار onSiteMessaging.enabled را روی true قرار دهید:

init('APP_ID', 'API_KEY', {
  onSiteMessaging: {
    enabled: true,
  },
});

رابط پیکربندی

interface OnSiteMessageConfig {
  enabled: boolean;  // Enable/disable on-site messaging (default: false)
}

نحوه عملکرد

روند تحویل پیام

1. SDK منتظر رویداد DOMContentLoaded صفحه می‌ماند.
2. SDK منتظر شناسایی کاربر (شناسه اتوماسیون) می‌ماند.
3. SDK به پیام‌های کمپین درون‌سایتی مربوط به آن کاربر گوش می‌دهد.
4. وقتی کمپین‌ها در دسترس باشند، یکی‌یکی نمایش داده می‌شوند.
5. وقتی یک پیام بسته شود یا منقضی شود، پیام بعدی در صف نمایش داده می‌شود.

نمایش پیام

پیام‌ها داخل یک iframe و درون یک Shadow DOM رندر می‌شوند. این جداسازی باعث می‌شود:

• از صفحه میزبان در برابر استایل‌ها و مارکاپ کمپین محافظت شود.
• اسکریپت‌های کمپین نتوانند بر اپلیکیشن شما اثر بگذارند.
• دکمه بستن و اندازه‌گیری خودکار iframe فراهم شود.

مدیریت کاربر

شناسایی کاربر (ضروری)

پیش از زمانی که کاربر به پیام‌های شخصی‌سازی‌شده نیاز دارد، او را شناسایی کنید:

import { authorizeUser } from '@metrixorg/websdk';
 
authorizeUser('user@example.com');
// or
authorizeUser('user-123');
// or
authorizeUser('custom_identifier');

شناسه سفارشی کاربر باید برای هر کاربر پایدار و منحصربه‌فرد باشد.

لغو شناسایی کاربر (خروج از حساب)

وقتی کاربر از حساب خود خارج می‌شود، هویت فعلی SDK را پاک کنید:

import { deauthorizeUser } from '@metrixorg/websdk';
 
deauthorizeUser();

پس از لغو شناسایی:

• هیچ فعالیت دیگری به کاربر قبلی نسبت داده نمی‌شود.
• نمایش پیام‌های درون‌سایتی برای آن کاربر متوقف می‌شود.
• برای فعال‌سازی مجدد برای یک کاربر جدید، دوباره authorizeUser() را فراخوانی کنید.

اکشن‌های پیام کمپین

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

1. بستن پیام

کاربر با کلیک روی دکمه بستن یا اکشن بستن تعریف‌شده در کمپین، پیام فعلی را می‌بندد.

2. باز کردن URL

کمپین می‌تواند یک URL را در یک تب جدید مرورگر باز کند:

// Campaign triggers this internally
window.open('https://example.com', '_blank');

3. ارسال رویداد

کمپین می‌تواند با استفاده از یک event slug یک رویداد Metrix ارسال کند:

// Campaign includes event slug
import { newEvent } from '@metrixorg/websdk';
 
newEvent('campaign_click', {
  campaign_id: 'campaign-123',
});

رویدادها باید شامل یک event slug باشند. ویژگی‌های سفارشی اختیاری هستند.

4. ارسال پاسخ

کمپین می‌تواند داده‌های پاسخ مرتبط با شناسه کمپین را ارسال کند:

// Response payload from campaign
{
  type: 'SEND_RESPONSE',
  payload: {
    action: 'subscribe',
    email: 'user@example.com'
  }
}

payloadهای پاسخ برای رهگیری، به شناسه کمپین مرتبط می‌شوند.

5. تنظیم اندازه نمایش

کمپین می‌تواند ابعاد iframe را بر اساس محتوا تنظیم کند:

{// Campaign scales iframe to fit content
  type: 'SCALE_IFRAME',
  width: 600,
  height: 400
}

مثال کامل

import { init, authorizeUser, deauthorizeUser } from '@metrixorg/websdk';
 
// Initialize SDK on app startup
init('APP_ID', 'API_KEY', {
  onSiteMessaging: {
    enabled: true,
  },
});
 
// When user logs in
document.getElementById('login-btn').addEventListener('click', async () => {
  // ... perform login ...
  const userId = 'user@example.com';
  
  // Authorize user to receive on-site messages
  authorizeUser(userId);
  
  console.log('User authorized, on-site messages enabled');
});
// When user logs out
document.getElementById('logout-btn').addEventListener('click', () => {
  // Clear SDK identity
  deauthorizeUser();
  
  console.log('User deauthorized, on-site messages disabled');
});

تنظیمات داشبورد

پیش از تست تحویل پیام:

1. ایجاد کمپین

   • وارد داشبورد Metrix شوید.
   • یک کمپین On-Site Messaging ایجاد کنید.
   • محتوای پیام و اکشن‌ها را طراحی کنید.

2. پیکربندی هدف‌گیری

   • شرایط مخاطب را تنظیم کنید (مثلاً سگمنت‌های خاص کاربران).
   • شرایط تریگر را تعریف کنید (مثلاً URL صفحه، زمان حضور در صفحه).
   • در صورت نیاز مدت نمایش پیام را تعیین کنید.

3. فعال‌سازی کمپین

   • مطمئن شوید وضعیت کمپین روی “Active” قرار دارد.
   • بررسی کنید که قوانین هدف‌گیری با کاربر تست شما مطابقت دارند.

4. تست تحویل

   • SDK را با onSiteMessaging.enabled: true راه‌اندازی کنید.
   • کاربر تست را با authorizeUser(testUserId) شناسایی کنید.
   • وب‌سایتی را که با شرایط کمپین مطابقت دارد بارگذاری کنید.
   • بررسی کنید که پیام نمایش داده می‌شود.

دردسترس‌بودن کمپین و هدف‌گیری آن کاملاً توسط داشبورد Metrix کنترل می‌شود. SDK هیچ متد عمومی برای اجبار نمایش پیام ارائه نمی‌دهد.

مرجع پیکربندی

راه‌اندازی SDK

init('APP_ID', 'API_KEY', {
  onSiteMessaging: {
    enabled: boolean;
  },
});

متدهای کاربر

// Authorize user
authorizeUser(customUserId: string): void
 
// Deauthorize userdeauthorizeUser(): void

ساختار پیام

رابط OnSiteMessage

interface OnSiteMessage {
  url: string;           // URL to iframe content
  alignment: string | null;  // Message position
  duration: number | null;   // Display duration in milliseconds
  campaignId: string;    // Campaign identifier
}

انواع پیام iframe

enum IframeMessageType {
  CLOSE_ONSITE = 'CLOSE_ONSITE',      // Close current message
  OPEN_URL = 'OPEN_URL',              // Open URL in new tab
  SEND_EVENT = 'SEND_EVENT',          // Send Metrix event
  SEND_RESPONSE = 'SEND_RESPONSE',    // Send response payload
  SCALE_IFRAME = 'SCALE_IFRAME',      // Adjust iframe size
}

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

1. مقداردهی اولیه قبل از شناسایی کاربر

همیشه قبل از authorizeUser()، متد init() را فراخوانی کنید:

// ✓ Correct order
init('APP_ID', 'API_KEY', { onSiteMessaging: { enabled: true } });
authorizeUser('user-id');
 
// ✗ Wrong order
authorizeUser('user-id');
init('APP_ID', 'API_KEY', { onSiteMessaging: { enabled: true } });

2. استفاده از شناسه‌های کاربری یکتا و پایدار

از شناسه‌های یکتا و ثابت استفاده کنید:

// ✓ Good - stable across sessions
authorizeUser('user@example.com');
authorizeUser('db-user-id-12345');
 
// ✗ Bad - changes each session
authorizeUser(Math.random().toString());
authorizeUser(Date.now().toString());

3. لغو شناسایی هنگام خروج از حساب

وقتی کاربر خارج می‌شود، همیشه شناسایی او را لغو کنید:

// ✓ Good
document.getElementById('logout-btn').addEventListener('click', () => {
  deauthorizeUser();  // Clear identity
  redirectToLoginPage();
});
 
// ✗ Bad - user still receives messages
document.getElementById('logout-btn').addEventListener('click', () => {
  redirectToLoginPage();  // Forgot to deauthorize
});

4. تست پس از بارگذاری کامل صفحه

پیام‌ها بعد از DOMContentLoaded بارگذاری می‌شوند، بنابراین تست را پس از بارگذاری کامل صفحه انجام دهید:

// ✓ Good - test after page loads
window.addEventListener('load', () => {
  authorizeUser('test-user');
  // Messages will now display if campaign matches
});
 
// ✗ Bad - may miss messages
authorizeUser('test-user');
// Don't reload or page might miss message loading

5. بررسی سازگاری مرورگرها

اطمینان حاصل کنید که مرورگر از APIهای موردنیاز پشتیبانی می‌کند:

• جاوااسکریپت فعال باشد.
• iframeها مجاز باشند.
• Shadow DOM پشتیبانی شود.
• APIهای اعلان‌ها در دسترس باشند (اگر از push استفاده می‌کنید).

عیب‌یابی

پیام‌ها نمایش داده نمی‌شوند

مشکل: پیام‌ها هرگز ظاهر نمی‌شوند.

• بررسی کنید: init() قبل از authorizeUser() اجرا شده باشد.
• بررسی کنید: onSiteMessaging.enabled روی true باشد.
• بررسی کنید: کاربر با authorizeUser() شناسایی شده باشد.
• بررسی کنید: کمپین در داشبورد Metrix فعال باشد.
• بررسی کنید: مخاطب/هدف‌گیری کمپین با کاربر تست مطابقت داشته باشد.
• بررسی کنید: برای تست تا DOMContentLoaded صبر کرده باشید.

پیام‌ها نمایش داده می‌شوند اما بلافاصله ناپدید می‌شوند

مشکل: پیام‌ها بلافاصله بسته می‌شوند.

• راه‌حل: تنظیمات مدت‌زمان کمپین را در داشبورد بررسی کنید.
• راه‌حل: مطمئن شوید محتوای پیام به‌درستی بارگذاری می‌شود.
• راه‌حل: کنسول مرورگر را برای خطاها بررسی کنید.

فقط یک پیام نمایش داده می‌شود

مشکل: صف پس از پیام اول متوقف می‌شود.

• راه‌حل: بررسی کنید کمپین دوم فعال و به‌درستی هدف‌گذاری شده باشد.
• راه‌حل: مطمئن شوید پیام اول به‌درستی بسته می‌شود.
• راه‌حل: پس از بسته‌شدن یک پیام، کمی صبر کنید تا پیام بعدی بارگذاری شود.

اکشن‌های کمپین کار نمی‌کنند

مشکل: اکشن‌های کلیک، URL یا event کار نمی‌کنند.

• بررسی کنید: مرورگر اجازه نمایش popup می‌دهد یا نه (برای اکشن URL).
• بررسی کنید: event slug درست باشد (برای اکشن event).
• بررسی کنید: کنسول مرورگر را برای خطاهای جاوااسکریپت بررسی کنید.
• بررسی کنید: محتوای کمپین بارگذاری می‌شود یا نه (تب Network را چک کنید).

خطاهای جاوااسکریپت در کنسول

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

• راه‌حل: مطمئن شوید SDK به‌درستی بارگذاری شده است.
• راه‌حل: وجود اسکریپت‌های تداخلی یا افزونه‌های مرورگر را بررسی کنید.
• راه‌حل: کش مرورگر را پاک کرده و دوباره بارگذاری کنید.
• راه‌حل: در حالت ناشناس/خصوصی مرورگر تست کنید تا تأثیر افزونه‌ها بررسی شود.

پشتیبانی

برای مشکلات یا پرسش‌ها:

• پیام‌ها نمایش داده نمی‌شوند؟ بخش عیب‌یابی بالا را بررسی کنید.
• کمپین اجرا نمی‌شود؟ مطمئن شوید کمپین در داشبورد Metrix فعال است.
• مشکل در شناسایی کاربر؟ مطمئن شوید authorizeUser() بعد از init() فراخوانی شده است.
• خطاهای جاوااسکریپت؟ کنسول مرورگر را بررسی کنید و وجود اسکریپت‌های تداخلی را چک کنید.