Web SDK: UTM والإسناد

تغطي هذه الصفحة تتبع UTM وإسناد الحملات في Joryio Web SDK. للتثبيت والإعداد ومرجع API الكامل، راجع دليل Web SDK.

يلتقط SDK تلقائيًا معاملات UTM من عناوين URL لإسناد الحملات والتحليلات التسويقية. يتيح لك ذلك معرفة الحملات التي تقود التحويلات وتحليل مسار المستخدم.

التقاط UTM تلقائيًا

يلتقط SDK، افتراضيًا، معاملات UTM القياسية الموجودة في URL:

• utm_source: مصدر الحملة، مثل "google" أو "newsletter".
• utm_medium: الوسيط التسويقي، مثل "email" أو "cpc" أو "social".
• utm_campaign: اسم الحملة، مثل "summer_sale" أو "product_launch".
• utm_content: محتوى الإعلان أو نسخته، مثل "banner_v1" أو "link_in_bio".
• utm_term: كلمات البحث المدفوعة، مثل "running+shoes".

ويلتقط أيضًا:

• referrer: مُحيل HTTP، مثل "https://google.com".
• landing_page: URL كامل لصفحة الهبوط مع معاملات الاستعلام.

// Example URL:
// https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale

// All events will automatically include:
{
  utm_source: "google",
  utm_medium: "cpc",
  utm_campaign: "spring_sale",
  referrer: "https://google.com/search?q=...",
  landing_page: "https://example.com/pricing?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale"
}

إسناد اللمسة الأولى والأخيرة

يتتبع SDK كلاً من اللمسة الأولى، أي الإسناد مدى الحياة، واللمسة الأخيرة، أي الإسناد الحديث:

اللمسة الأولى: تُلتقط في أول زيارة للمستخدم ولا تُستبدل أبدًا:

first_touch_utm_source: "facebook"
first_touch_utm_medium: "social"
first_touch_utm_campaign: "awareness_campaign"
first_touch_landing_page: "https://example.com/?utm_source=facebook..."
first_touch_captured_at: "2024-01-15T10:30:00Z"

اللمسة الأخيرة: تُحدَّث كلما اكتُشفت معاملات UTM جديدة:

last_touch_utm_source: "google"
last_touch_utm_medium: "cpc"
last_touch_utm_campaign: "conversion_campaign"
last_touch_landing_page: "https://example.com/pricing?utm_source=google..."
last_touch_captured_at: "2024-02-20T15:45:00Z"

يساعد نموذج الإسناد المزدوج هذا في الإجابة عن:

• اللمسة الأولى: "من أين أتى هذا المستخدم في الأصل؟"
• اللمسة الأخيرة: "ما نقطة التفاعل الأخيرة قبل التحويل؟"

خيارات الإعداد

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',

  // UTM tracking is enabled by default
  captureUTM: true,

  // Start new session when campaign changes
  resetSessionOnNewCampaign: false,

});

تفاصيل الإعداد:

• captureUTM، الافتراضي true: التقاط معاملات UTM من URL تلقائيًا.
• resetSessionOnNewCampaign، الافتراضي false: بدء جلسة جديدة عند تغيّر معاملات UTM، على نحو مشابه لـ Amplitude.
• يُضمّن المُحيل وصفحة الهبوط في خصائص الحدث افتراضيًا.

تتبع UTM على مستوى الجلسة

تُخزن معاملات UTM على مستوى الجلسة لتتمكن من تحليل رحلة المستخدم كاملة:

// User arrives from Google Ads campaign
// URL: ?utm_source=google&utm_medium=cpc&utm_campaign=spring_sale

// First event in session
joryio.track('Page Viewed', { page: '/landing' });
// Includes: utm_source, utm_medium, utm_campaign, referrer, landing_page

// User navigates to pricing (no UTM in URL)
joryio.track('Page Viewed', { page: '/pricing' });
// Still includes: utm_source="google", utm_medium="cpc", utm_campaign="spring_sale"

// All events in this session will carry the campaign attribution
joryio.track('Trial Started');
// Includes: utm_source="google", utm_medium="cpc", utm_campaign="spring_sale"

إعادة ضبط الجلسة عند حملة جديدة

فعّل resetSessionOnNewCampaign لبدء جلسات جديدة حين يصل المستخدمون من حملات مختلفة:

const joryio = new JoryioSDK({
  sdkKey: 'jry_sdk_web_...',
  resetSessionOnNewCampaign: true,
});

// Session 1: User from Facebook
// URL: ?utm_source=facebook&utm_medium=social
// session_id: "sess_123"

// Session 2: Same user returns from Google (new session starts)
// URL: ?utm_source=google&utm_medium=cpc
// session_id: "sess_456" (new session ID)

يفيد ذلك في:

• تحليلات دقيقة للجلسات على مستوى الحملة.
• منع التباس الإسناد عندما يصل المستخدمون من حملات متعددة.
• تحليل سلوك المستخدمين الخاص بكل حملة.

تحديث UTM يدويًا في SPA

لتطبيقات الصفحة الواحدة التي تغيّر URLs دون إعادة تحميل الصفحة:

// When URL changes in your SPA
window.addEventListener('popstate', () => {
  joryio.updateUTM();
});

// Or in your router
router.on('route-change', () => {
  joryio.updateUTM();
});

// React Router example
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    // Update UTM on route change
    joryio.updateUTM();
  }, [location]);
}

الوصول إلى بيانات UTM

اجلب بيانات UTM الحالية برمجيًا:

// Get all UTM data
const utmData = joryio.getUTMData();

console.log(utmData);
// {
//   current: {
//     utm_source: "google",
//     utm_medium: "cpc",
//     utm_campaign: "spring_sale",
//     referrer: "https://google.com",
//     landing_page: "https://example.com/?utm_source=google...",
//     captured_at: 1705319400000
//   },
//   firstTouch: {
//     utm_source: "facebook",
//     utm_medium: "social",
//     utm_campaign: "awareness",
//     captured_at: 1704715200000
//   },
//   lastTouch: {
//     utm_source: "google",
//     utm_medium: "cpc",
//     utm_campaign: "spring_sale",
//     captured_at: 1705319400000
//   }
// }

// Use in your application
const { current, firstTouch, lastTouch } = joryio.getUTMData();

if (current?.utm_source === 'google') {
  // Show special offer for Google traffic
}

حالات الاستخدام

1. تحليل أداء الحملة

// Track conversions with full attribution
joryio.track('Order Completed', {
  order_id: 'order_123',
  revenue: 99.99
});
// Automatically includes UTM parameters for attribution

2. نسخ الحملات في اختبار A/B

// Track which ad creative drives conversions
// URL: ?utm_content=banner_v1
joryio.track('Signup Completed');
// Can analyze: which utm_content value has highest conversion rate

3. الإسناد متعدد اللمسات

// See the full user journey
const { firstTouch, lastTouch } = joryio.getUTMData();

joryio.track('Purchase', {
  order_value: 299.99,
  // First touch: where they came from originally
  discovered_via: firstTouch?.utm_source,
  // Last touch: what drove the final conversion
  converted_via: lastTouch?.utm_source
});

4. تحليل المسار

// Analyze drop-off by campaign
joryio.track('Checkout Started');  // Auto-includes UTM
joryio.track('Payment Info Added'); // Same UTM
joryio.track('Order Completed'); // Same UTM

// Now you can segment funnel by utm_campaign to see which campaigns
// have the best conversion rates through each step

اعتبارات الخصوصية

تُخزن معاملات UTM ومعلومات المُحيل في localStorage، وتُمسح عندما:

• يستدعي المستخدم joryio.reset() عند تسجيل الخروج.
• يمسح المستخدم بيانات المتصفح.

يستمر إسناد اللمسة الأولى والأخيرة عبر الجلسات للمستخدم نفسه إلى أن يمسح بياناته أو يسجل الخروج؛ إذ لا يملك localStorage انتهاء صلاحية مدمجًا.