التحليلات

اجلب تحليلات الملفات التعريفية على Google وBing وFacebook باستخدام SDK الخاص بـ listingsapi-js.

تسترجع دوال التحليلات إحصاءات على مستوى المنصة، مثل مرات الظهور في البحث والنقرات وطلبات الاتجاهات والمكالمات الهاتفية، من Google Business Profile وBing Places وصفحات Facebook. تتوفر جميع دوال التحليلات مباشرةً على مثيل العميل ListingsAPI، ويقتصر نطاقها على معرّف موقع. تُرمَّز معرّفات المواقع الرقمية تلقائيًا، لذا يمكن استخدام 16808 و'TG9jYXRpb246MTY4MDg=' بالتبادل.

للدوال الثلاث جميعها التوقيع نفسه: معرّف موقع بالإضافة إلى نطاق { fromDate, toDate } اختياري. كلا التاريخين اختياري، ويمكن حذف أحدهما أو كليهما؛ احذفهما لاستخدام الفترة الافتراضية لإعداد التقارير في المنصة.

كل مقياس عبارة عن سلسلة زمنية

لا تتضمن هذه البيانات أي إجماليات على هيئة قيم مفردة. كل مقياس عبارة عن مصفوفة من نقاط { startTime, value }، نقطة واحدة لكل يوم (لكل أسبوع في Bing)، ويكون المقياس الذي لا تتوفر لديك بيانات له null بدلًا من 0 أو []. لذا احسب مجموع قيم السلسلة بنفسك، وميّز بين "لا توجد بيانات" و"صفر":

type Point = { startTime: string; value: number | null }; // null when the metric is absent, so an empty profile never reads as 0.function sumSeries(series: Point[] | null | undefined): number | null {if (!Array.isArray(series)) return null;return series.reduce((acc, p) => acc + (p.value ?? 0), 0);} function show(label: string, series: Point[] | null | undefined) {const total = sumSeries(series);console.log(label, total === null ? 'unavailable' : total);}

fetchGoogleAnalytics

اجلب إحصاءات Google Business Profile لموقع.

const google = await client.fetchGoogleAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Impressions (total)', google.total);show('Search impressions', google.search);show('Maps impressions', google.maps);show('Website clicks', google.websiteAction);

الخيارات

البيانات المُرجَعة هي الكائن googleInsights، وكل مفتاح فيه يقابله سلسلة { startTime, value }[]: total وsearch وmaps وwebsiteAction وdirectionsAction وphoneAction وbusinessBookings وbusinessFoodOrders وbusinessFoodMenuClicks. يمثّل total مرات ظهور الملف التجاري، أي مجموع search وmaps؛ ولا يشمل مقاييس الإجراءات. تُرجَع أي سلسلة لا تتوفر لدى Google بيانات لها بالقيمة null. راجع الحصول على تحليلات Google لموقع للاطلاع على المرجع الكامل للحقول.

fetchBingAnalytics

اجلب إحصاءات Bing Places لموقع.

const bing = await client.fetchBingAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Bing views', bing.views);

يوفّر Bing مقياسًا واحدًا، هو views، تُجمَّع بياناته أسبوعيًا بدلًا من يوميًا.

الخيارات

fetchFacebookAnalytics

اجلب إحصاءات صفحة Facebook لموقع.

const facebook = await client.fetchFacebookAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Page views', facebook.views);show('CTA clicks', facebook.ctaAction);

تتضمن البيانات المُرجَعة من Facebook كلًا من views وctaAction وwebsiteAction وdirectionsAction وphoneAction. ولا تتضمن pageLikes.

الخيارات

تقرير متعدد المنصات

اجلب بيانات المنصات الثلاث جميعها بالتوازي باستخدام Promise.all:

import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from envconst LOCATION_ID = 16808;const range = { fromDate: '2024-01-01', toDate: '2024-12-31' }; const [google, bing, facebook] = await Promise.all([client.fetchGoogleAnalytics(LOCATION_ID, range),client.fetchBingAnalytics(LOCATION_ID, range),client.fetchFacebookAnalytics(LOCATION_ID, range),]); show('Google impressions:', google.total);show('Bing views:', bing.views);show('Facebook views:', facebook.views);

إذا لم يكن الملف التجاري متصلًا بمنصة معيّنة، تُكمل الدالة التنفيذ بنجاح وتُرجع كائنًا فارغًا بدلًا من الرفض، وتُرجَع السلسلة الفردية بالقيمة null. اعرض هذه الحالة على أنها "غير متاحة" بدلًا من تحويلها قسرًا إلى 0 باستخدام ??، وإلا فستظهر بيانات الملف التجاري غير المتصل على هيئة صفر فعلي في لوحة التحكم. تظل حالات فشل الطلبات تطرح أخطاء SDK ذات الأنواع المحددة.

موارد ذات صلة

• المواقع: البحث عن معرّفات المواقع
• التقييمات: تحليلات التقييمات (overview وtimeline وsites-stats)
• حالات الاستخدام: خطوات إعداد تقرير تحليلات