Analytics

يمكنك الاشتراك في أحداث إحصاءات "الأماكن" حول نقر المستخدمين على "الاتجاهات" أو "الاتصال" أو "الموقع الإلكتروني" أو فتح "خرائط Google" أو النقر على التقييم بالنجوم أو على اسم المؤلف أو فتح مربّع عرض الصور أو تبديل علامات التبويب. يوفّر كل حدث مجموعة من العلامات وأقرب عنصر gmp-* علني يحتوي على التفاعل (أو null)، والذي يمكنك من خلاله قراءة رقم تعريف المكان وموقعه الجغرافي.

أحداث "إحصاءات Google" المقدَّمة

يعرض الجدول التالي أمثلة على أحداث الإحصاءات التي توفّرها حزمة أدوات "خرائط Google" الجاهزة للأماكن.

التفاعل مع واجهة المستخدم tags: Set<string>
زرّ الاتجاهات {"click", "directions", "outbound"}
زر "فتح في خرائط Google" {"click", "maps", "outbound"}
زر الاتصال / رقم الهاتف (علامة التبويب "نظرة عامة") {"click", "call_place", "outbound"}
زرّ الموقع الإلكتروني / الموقع الإلكتروني (علامة التبويب "نظرة عامة") {"click", "place_website", "outbound"}
رابط تحديد المصدر {"click", "attribution", "outbound"}
رابط التقييم {"click", "reviews", "outbound"}
رابط الإفصاح القانوني (روابط مربّعات الحوار في "ⓘ") {"click", "disclosure", "outbound"}
رابط الإبلاغ {"click", "report", "outbound"}
رابط المراجعة {"click", "review", "outbound"}
رابط الوسائط / الصورة {"click", "media", "outbound"}
تم فتح "العرض المبسّط للصور" (داخل التطبيق) {"click", "media"}
تم اختيار علامة التبويب "نظرة عامة" (في التطبيق) {"click", "overview_tab"}
تم اختيار علامة التبويب "المراجعات" (داخل التطبيق) {"click", "reviews_tab"}
تم اختيار علامة التبويب "لمحة" (في التطبيق) {"click", "about_tab"}
تم فتح القائمة الكاملة للمراجعات (⋮) (داخل التطبيق) {"click", "reviews_menu"}
تم فتح القائمة الكاملة في Lightbox (⋮) (داخل التطبيق) {"click", "lightbox_menu"}
تم فتح قائمة الملخّصات المستندة إلى الذكاء الاصطناعي التوليدي (⋮) (داخل التطبيق) {"click", "generative_summary_menu"}
تم فتح قائمة ملخّص المراجعات المستنِدة إلى الذكاء الاصطناعي التوليدي (⋮) {"click", "review_summary_menu"}

بما أنّه قد تتم إضافة أحداث وعلامات جديدة بمرور الوقت، يمكنك إرفاق معالج عام أثناء التطوير لتسجيل كل حدث يتم بثه أثناء تفاعلك مع أحد المكوّنات:

const {Settings} = await google.maps.importLibrary('core');

// Log every gmp-analytics event broadcast on the page
Settings.getInstance().addEventListener('gmp-analytics', (event) => {
  console.log('Analytics event:', event);
});

الاشتراك في أحداث الإحصاءات ومعالجتها

يمكنك تتبُّع أحداث الإحصاءات في جميع عناصر حزمة أدوات "خرائط Google" الجاهزة للأماكن على الصفحة من خلال إضافة متتبِّع الأحداث gmp-analytics إلى مثيل singleton google.maps.Settings.

يوفّر google.maps.AnalyticsEvent السمة event.tags (Set<string>) وevent.element (Element | null يمثّل أقرب عنصر gmp-* متاح للجميع يحتوي على التفاعل، مثل gmp-place-details-compact أو null إذا لم ينطبق أي منهما). عند توفّرها، يمكنك قراءة Place المرتبطة من event.element.place (أو event.element.places في عناصر القائمة والبحث).

const {Settings} = await google.maps.importLibrary('core');
const {Place} = await google.maps.importLibrary('places');

const settings = Settings.getInstance();

settings.addEventListener('gmp-analytics', (event) => {
  const {tags, element} = event; // google.maps.AnalyticsEvent
  const place = element?.place;
  const placeId = place instanceof Place ? place.id : 'none';

  // Option A: Check for specific interactions using tag strings
  if (tags.has('directions')) {
    console.log(`User requested directions for place: ${placeId}`);
  }

  if (tags.has('outbound')) {
    console.log(`User is leaving the page via: ${[...tags].sort().join(', ')}`);
  }

  // Option B: Forward every event to your analytics pipeline (for instance, Google Analytics / gtag)
  gtag('event', 'maps_javascript_api_analytics', {
    element_tag: element?.localName ?? 'none',
    tags: [...tags].sort().join(','),
    place_id: placeId,
  });
});

إذا كانت صفحتك تعرض عناصر متعددة من حزمة أدوات "خرائط Google" الجاهزة للأماكن، يمكنك مقارنة event.element بمرجع عنصر DOM معيّن لتحديد مثيل البطاقة الذي بدأ الحدث:

const {Settings} = await google.maps.importLibrary('core');

const featuredCard = document.querySelector('#featured-place-card');

Settings.getInstance().addEventListener('gmp-analytics', (event) => {
  if (event.element?.contains(featuredCard) && event.tags.has('directions')) {
    console.log('Directions clicked on the featured place card:', featuredCard.place?.id);
  }
});