الفصل 4 / 9
كيف تدخل البيانات إلى Amplitude، وإلى أين تخرج؟
تدخل البيانات إلى Amplitude من عدة أبواب، لكنها كلها تُكتب في نموذج الـ events نفسه وفي هوية المستخدم نفسها. اختيار الباب يكاد يطابق تمامًا قرار SDK مقابل S2S الذي تعرفه من Adjust.
- ستعرف متى تستخدم الـ SDK و HTTP API والتكاملات والـ warehouse.
- ستقرأ أنماط الكود الأساسية للهاتف والويب والـ backend.
- ستعرف كيف تتجنّب العدّ المزدوج عندما تسلك الإشارة نفسها طريقين.
التدفّق العام
SDK و S2S: التقسيم نفسه في الأداتين
القاعدة التي تعرفها من Adjust تنطبق هنا أيضًا: events السلوك تأتي من الجهاز؛ أما events المال المُتحقَّق منها والـ events التي تقع والتطبيق مغلق فتأتي من الخادم.
| نوع الـ event | الطريق الموصى به | السبب |
|---|---|---|
| مشاهدة الشاشات، النقرات، البحث | SDK | سياق الجلسة والجهاز يأتي تلقائيًا |
| خطوات الـ onboarding | SDK | يُقاس السلوك المجهول قبل تسجيل الدخول |
| الشراء (المُتحقَّق منه) | 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);import { init, track, setUserId, identify, Identify } from '@amplitude/analytics-react-native';
// 1. Initialize once at app start
init('YOUR_API_KEY');
// 2. Track an event
track('Product Viewed', { product_id: 'SKU-1042', category: 'headphones', price: 49.9 });
// 3. Identify after login
setUserId('cust_88231');
// 4. User properties
const event = new Identify();
event.set('plan', 'premium');
identify(event);import AmplitudeSwift
// 1. Initialize once, e.g. in AppDelegate
let amplitude = Amplitude(configuration: Configuration(apiKey: "YOUR_API_KEY"))
// 2. Track an event
amplitude.track(eventType: "Product Viewed",
eventProperties: ["product_id": "SKU-1042", "price": 49.9])
// 3. Identify after login
amplitude.setUserId(userId: "cust_88231")
// 4. User properties
let identify = Identify()
identify.set(property: "plan", value: "premium")
amplitude.identify(identify: identify)import com.amplitude.android.Amplitude
import com.amplitude.android.Configuration
import com.amplitude.core.events.Identify
// 1. Initialize once, e.g. in Application.onCreate
val amplitude = Amplitude(Configuration(apiKey = "YOUR_API_KEY", context = applicationContext))
// 2. Track an event
amplitude.track("Product Viewed", mutableMapOf("product_id" to "SKU-1042", "price" to 49.9))
// 3. Identify after login
amplitude.setUserId("cust_88231")
// 4. User properties
amplitude.identify(Identify().set("plan", "premium"))# Server-side event after the backend has verified the renewal
curl -X POST https://api2.amplitude.com/2/httpapi \
-H 'Content-Type: application/json' \
-d '{
"api_key": "YOUR_API_KEY",
"events": [{
"user_id": "cust_88231",
"event_type": "Subscription Renewed",
"time": 1762243200000,
"insert_id": "renewal-cust_88231-2026-11",
"event_properties": { "plan": "premium", "period": "monthly" },
"revenue": 9.99
}]
}'أسماء حزم الـ SDK وتواقيع الدوال وخيارات التهيئة تتغيّر بين الإصدارات؛ والفرق بين الـ SDKs القديمة (legacy) والجيل الأحدث كبير بشكل خاص. راجع توثيق إصدار الـ SDK المستخدم في المشروع قبل استخدامها في تكامل لعميل. يستخدم HTTP API نقطة نهاية مختلفة لإقامة البيانات في الاتحاد الأوروبي، وهناك نقطة نهاية batch منفصلة للأحجام الكبيرة.
ما يجب الانتباه إليه في events الخادم
- الهوية: لربط event الخادم بالشخص الصحيح، أرسل قيمة
user_idنفسها الموجودة على الجهاز. فقط events الخادم للمستخدمين المسجّلين ترتبط بشكل صحيح. - الوقت: حقل
timeهو لحظة وقوع الـ event (بالملّي ثانية)، لا لحظة إرساله. - إعادة الإرسال: استخدم
insert_idنفسه عند إعادة المحاولة؛ يعدّ Amplitude الـinsert_idالمتكرر كـ event واحد ضمن فترة معيّنة. - الجلسة: events الخادم ليست جزءًا من جلسة المستخدم في التطبيق، ولا يُتوقّع أن تؤثّر على مقاييس مثل مدة الجلسة.
في 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 الثلاثة في سلسلة الشخص نفسه.