دليل تعلّم Amplitude
في نهاية هذا الفصل
  • ستعرف متى تستخدم الـ SDK و HTTP API والتكاملات والـ warehouse.
  • ستقرأ أنماط الكود الأساسية للهاتف والويب والـ backend.
  • ستعرف كيف تتجنّب العدّ المزدوج عندما تسلك الإشارة نفسها طريقين.

التدفّق العام

كل مصدر يُدمج في هوية مستخدم واحدة، ومنها يخرج التحليل Mobile SDKiOS، Android، React Native، Flutter Web SDKevents المتصفح HTTP APIevents من الـ backend تكامل Adjustattribution → user property Warehouse importSnowflake، BigQuery وغيرها مشروع Amplitude Events + properties User properties دمج الهوية device_id + user_id → Amplitude ID مخططات التحليلFunnel، retention، المسارات مزامنة الـ cohortsإلى أدوات الإعلان و CRM Warehouse exportبيانات الـ events الخام
كل مدخل يكتب في المشروع نفسه. الباب الذي ترسل منه الـ event يحدّد بأي مستخدم وبأي جلسة يرتبط.

SDK و S2S: التقسيم نفسه في الأداتين

القاعدة التي تعرفها من Adjust تنطبق هنا أيضًا: events السلوك تأتي من الجهاز؛ أما events المال المُتحقَّق منها والـ events التي تقع والتطبيق مغلق فتأتي من الخادم.

من الجهاز التطبيق Adjust SDK Amplitude SDK الشاشات، النقرات، البحث، الإضافة إلى السلة، خطوات الـ onboarding. معلومات الجلسة والجهاز تُضاف تلقائيًا. من الخادم Backend Adjust S2S Amplitude HTTP API مشتريات مُتحقَّق منها، تجديد الاشتراكات، الاستردادات، أي شيء والتطبيق مغلق. لا توجد معلومات جهاز؛ أنت تقدّم الهوية.
في إعداد العميل المعتاد، يرسل التطبيق نفسه البيانات إلى الأداتين من الجهاز ومن الخادم معًا. أي event يسلك أي طريق يُقرَّر لكل أداة على حدة.
نوع الـ eventالطريق الموصى بهالسبب
مشاهدة الشاشات، النقرات، البحثSDKسياق الجلسة والجهاز يأتي تلقائيًا
خطوات الـ onboardingSDKيُقاس السلوك المجهول قبل تسجيل الدخول
الشراء (المُتحقَّق منه)HTTP API، بعد تحقّق الـ backendلا تُحتسب العمليات المزيّفة أو الملغاة
تجديد الاشتراك، الاستردادHTTP APIيحدث والمستخدم خارج التطبيق
تغيّر حالة من الـ CRM (مثل ترقية الخطة)HTTP API أو استدعاء identifyالمصدر هو الـ backend
العدّ المزدوج

إذا أرسلت عملية الشراء نفسها كـ Purchase من الـ SDK وكـ Purchase من الـ backend، فستحصل على event مرتين. إما أن تختار طريقًا واحدًا، أو تفصل الأسماء (Purchase Attempted من الجهاز و Purchase Completed من الخادم). على جانب الخادم، أعطِ كل event قيمة insert_id فريدة للحماية من إعادة الإرسال.

أنماط الكود

في كل SDK أربع عمليات أساسية: التهيئة، إرسال event، تعريف المستخدم، تحديث خصائص المستخدم. تعرض الأمثلة أدناه هذه العمليات الأربع جنبًا إلى جنب.

import * as amplitude from '@amplitude/analytics-browser';

// 1. Initialize once, as early as possible
amplitude.init('YOUR_API_KEY');

// 2. Track an event with properties
amplitude.track('Product Viewed', {
  product_id: 'SKU-1042',
  category: 'headphones',
  price: 49.9,
});

// 3. Identify the user after login
amplitude.setUserId('cust_88231');

// 4. Update persistent user properties
const identify = new amplitude.Identify();
identify.set('plan', 'premium');
identify.setOnce('signup_date', '2026-11-04');
identify.add('orders_count', 1);
amplitude.identify(identify);

// Revenue as a dedicated call
const revenue = new amplitude.Revenue()
  .setProductId('SKU-1042')
  .setPrice(49.9)
  .setQuantity(1);
amplitude.revenue(revenue);
تحقّق

أسماء حزم الـ SDK وتواقيع الدوال وخيارات التهيئة تتغيّر بين الإصدارات؛ والفرق بين الـ SDKs القديمة (legacy) والجيل الأحدث كبير بشكل خاص. راجع توثيق إصدار الـ SDK المستخدم في المشروع قبل استخدامها في تكامل لعميل. يستخدم HTTP API نقطة نهاية مختلفة لإقامة البيانات في الاتحاد الأوروبي، وهناك نقطة نهاية batch منفصلة للأحجام الكبيرة.

ما يجب الانتباه إليه في events الخادم

  • الهوية: لربط event الخادم بالشخص الصحيح، أرسل قيمة user_id نفسها الموجودة على الجهاز. فقط events الخادم للمستخدمين المسجّلين ترتبط بشكل صحيح.
  • الوقت: حقل time هو لحظة وقوع الـ event (بالملّي ثانية)، لا لحظة إرساله.
  • إعادة الإرسال: استخدم insert_id نفسه عند إعادة المحاولة؛ يعدّ Amplitude الـ insert_id المتكرر كـ event واحد ضمن فترة معيّنة.
  • الجلسة: events الخادم ليست جزءًا من جلسة المستخدم في التطبيق، ولا يُتوقّع أن تؤثّر على مقاييس مثل مدة الجلسة.
من جهة Adjust

في Adjust S2S تحتاج إلى معرّفات الجهاز (ADID و IDFA/GAID وغيرها) لربط الـ event بالجهاز الصحيح؛ والـ event بدون معرّف لا يُطابق. في Amplitude HTTP API المقابل هو user_id أو device_id. إذا كان الـ backend نفسه يرسل إلى الأداتين، فعليه أن يحفظ مجموعتي المعرّفات معًا.

متى تظهر events الـ SDK؟

لا ترسل الـ SDKs الـ events فورًا؛ بل تضعها في طابور على الجهاز وترسلها دفعةً عند بلوغ عدد أو مدة معيّنة. وبدون إنترنت تنتظر. لذلك قد يستغرق وصول الـ event ثوانٍ، أو ساعات في حالة عدم الاتصال، لكن حقل time يحمل دائمًا لحظة وقوعه.

نصيحة

عند اختبار التكامل، استخدم user lookup و ingestion debugger بدل البحث عن الـ event في المخططات. هما ما يقابل Testing Console في Adjust، ويُظهران تقريبًا فورًا ما إذا وصل الـ event وبأي خصائص.

البيئات: أين الـ sandbox؟

في Adjust توجد بيئتا sandbox و production داخل التطبيق نفسه ويُفصل بينهما بفلتر. في Amplitude الممارسة الشائعة هي مشاريع منفصلة للتطوير والإنتاج. لكل مشروع API key خاص به، وإعدادات البناء تحدّد أي مفتاح يُستخدم.

خطأ شائع

إصدار build للتطوير بمفتاح API الخاص بالإنتاج. تختلط events الاختبار بالبيانات الحقيقية ويصعب تنظيفها. أنشئ بنية تختار المفتاح حسب بيئة البناء وتحقّق منها قبل الإطلاق.

العمل مع الـ warehouse

إذا كانت البيانات موجودة أصلًا في warehouse (مثل events الـ backend في BigQuery)، يمكن لـ Amplitude استيرادها. وفي الاتجاه المعاكس، يمكن تصدير events الخام من Amplitude إلى warehouse للتحليل والنسخ الاحتياطي. هذا هو الجزء الأكثر تقاطعًا مع أعمال Ryze في ربط واجهات الـ API بالـ warehouse.

تحقّق

مصادر الـ warehouse ووجهاته المدعومة وتكرار المزامنة والخطة التي تتوفر فيها قد تتغيّر. راجع القائمة الحالية في كتالوج تكاملات Amplitude.

تمرين

أنشئ مشروعًا تجريبيًا مجانيًا. أضف Web SDK إلى صفحة HTML بسيطة، واربط track بزر و setUserId بزر "تسجيل الدخول". ثم أرسل event خادم للمستخدم نفسه من الطرفية باستخدام مثال HTTP API أعلاه. تحقّق في user lookup من ظهور الـ events الثلاثة في سلسلة الشخص نفسه.