AMP

نظرة عميقة على AMP Analytics

Important: this documentation is not applicable to your currently selected format email!

يقدم هذا الدليل رؤية متعمقة على amp-analytics، حيث يقسّم نموذج تهيئة amp-analytics إلى ثلاثة مكونات أساسية مهمة:

ويستخدم باقي هذا الدليل نموذج التهيئة هذا، الذي يتتبع مرات مشاهدة الصفحة ونقرات المستخدم على الروابط ويرسل بيانات التحليلات إلى مزوّد الجهة الخارجية، Google Analytics:

<amp-analytics type="googleanalytics" config="https://example.com/analytics.account.config.json">
<script type="application/json">
{
  "requests": {
    "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}",
    "event": "https://example.com/analytics?eid=${eventId}&elab=${eventLabel}&acct=${account}"
  },
  "vars": {
    "account": "ABC123"
  },
  "extraUrlParams": {
    "cd1": "AMP"
  },
  "triggers": {
    "trackPageview": {
      "on": "visible",
      "request": "pageview"
    },
    "trackAnchorClicks": {
      "on": "click",
      "selector": "a",
      "request": "event",
      "vars": {
        "eventId": "42",
        "eventLabel": "clicked on a link"
      }
    }
  },
  'transport': {
    'beacon': false,
    'xhrpost': false,
    'image': true
  }
}
</script>
</amp-analytics>

ملاحظة: الغرض من نموذج الشفرة أعلاه هو مساعدتك على التعلّم، لكنه ليس نموذجًا حقيقيًا على الإطلاق. إذا كنت تعمل مع مزودي تحليلات، فلن يكون للنموذج أعلاه - على الأرجح - أي معنى؛ فتهيئات المزوّد تزيل التعقيد. راجع مستندات مزوّد التحليلات التابع له للاطلاع على نماذج التهيئات.

وجهة إرسال بيانات التحليلات: السمة type

تم تصميم AMP لدعم النمطين الشائعين لتجميع البيانات:

  • التحويل بواسطة نقطة نهائية مملوكة للناشر لأجل أنظمة التحليلات الداخلية.
  • التحويل بواسطة نقطة نهائية مملوكة لمورّد لإتاحة التوافقية مع حل المورّد (مثل Adobe Analytics.

لإرسال بيانات التحليلات إلى مزوّد تحليلات، ضمّن السمة type في العلامة amp-analytics وعيّن قيمتها على المورّد المناسب، وذلك على النحو المحدّد في مواصفة amp-analytics.

على سبيل المثال: يرسل <amp-analytics type="googleanalytics"> بيانات التحليلات إلى مزوّد التحليلات الذي يمثل جهة خارجية، وهو Google Analytics. لإرسال البيانات إلى نقطة نهائية مملوكة لناشر، ببساطة لا تضمّن السمة type. سيتم إرسال بيانات التحليلات إلى النقاط النهائية المحددة لكل طلب.

تهيئات مورّد Analytics هي وسيلة سريعة لبدء العمل باستخدام amp-analytics. ينبغي لك الرجوع إلى مستندات المورّد وموارد المساعدة لمزيد من الإرشادات. كما ذكرنا سابقًا، يمكن العثور على قائمة المورّدين الذين نفذوا بالفعل إجراء الدمج مع AMP، وكذلك الروابط إلى مستنداتهم الخاصة، في مواصفة amp-analytics.

إذا كنت مورّد تحليلات، فتعرّف على المزيد بشأن دمج تهيئة تحليلاتك في AMP HTML.

تحميل تهيئة بعيدة: السمة config

لست مضطرًا إلى تضمين كل التهيئة لأجل amp-analytics كاملةً في صفحتك على AMP. بدلاً من ذلك، يمكنك الاستدعاء إلى عنوان URL بعيد لكل التهيئات أو جزء منها.

يسمح لك هذا بتنفيذ إجراءات، مثل تغيير التهيئة استنادًا إلى طلب معين. إذا كنت تمتلك، بوصفك ناشرًا، إمكانية التحكم في ملف بعيد يمكنك إجراء أي معالجة من جهة الخادم تكون ضرورية لإنشاء بيانات التهيئة.

الخطوة الأولى لتحميل التهيئات البعيدة هي تضمين السمة config في العلامة amp-analytics:

<amp-analytics config="https://example.com/analytics.account.config.json">

الخطوة التالية هي إنشاء محتوى JSON المتضمّن في عنوان URL البعيد. في هذا النموذج البسيط، لا تمثل التهيئة المضمّنة في كائن JSON سوى قيمة المتغير لحساب التحليلات.

نموذج المحتوى في https://example.com/analytics.account.config.json:

{
  "vars": {
    "account": "UA-XXXXX-Y"  // Replace with your property ID.
  }
}

الخطوة النهائية هي التأكّد من سحب ما يحتويه الملف البعيد إلى الموضع السليم في تهيئة amp-analytics. في كلّ من طلبي pageview وevent هنا، يتم تعيين قيمة المتغير account تلقائيًا على قيمة الحساب في عنوان URL البعيد ("account": "UA-XXXXX-Y"):

"requests": {
  "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}",
  "event": "https://example.com/analytics?eid=${eventId}&elab=${eventLabel}&acct=${account}"
}

مهم: لا يتم التحقق من AMP مقابل الاستخدامات العديدة للمتغير نفسه. يتم ملء القيم عبر اتباع ترتيب استبدال متغير حسب التفضيل، وتكون القيم في عناوين URL البعيدة في قمة ذلك الترتيب (انظر ترتيب استبدال المتغير.

السمات Requests وtriggers وtransports

تحدّد السمة requests "ماهية البيانات التي يتم إرسالها" (على سبيل المثال، pageviews، وevents)، والموضع الذي يتم إرسالها إليه (عناوين URL المستخدمة لنقل البيانات).

تصف السمة triggers الموعد الذي يتعين إرسال بيانات التحليلات فيه، على سبيل المثال، عندما يعرض مستخدم صفحة، أو عندما ينقر مستخدم فوق رابط.

تحدد السمة transport كيفية إرسال طلب، وبشكل أكثر تحديدًا، البروتوكول.

تابع القراءة للتعرّف على المزيد بشأن هذه التهيئات. (يمكنك أيضًا القراءة بشأن هذه التهيئات في amp-analytics

ماهية البيانات التي يتم إرسالها: السمة requests

يتم استخدام request-name في تهيئة المشغل لتحديد الطلب الذي ينبغي إرساله ردًا على حدث خاص. يمثل request-value عنوان URL لـ https. يمكن أن تتضمن هذه القيم الرموز المميزة للعنصر النائب الذي يمكن أن يشير إلى الطلبات أو المتغيرات الأخرى.

"requests": {
  "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}",
  "event": "https://example.com/analytics?eid=${eventId}&elab=${eventLabel}&acct=${account}"
}

بعض مزوّدي التحليلات (بما في ذلك Google Analytics) قدموا بالفعل التهيئة التي تستخدمها عبر السمة type. إذا كنت تستخدم مزوّد تحليلات، فقد لا تحتاج إلى تضمين معلومات requests. راجع مستندات مورّدك للتعرّف على ما إذا كانت هناك حاجة لتهيئة requests أم لا وكيفية ذلك.

إلحاق عنوان URL للطلب: معلمات عنوان URL الإضافية

تحدد السمة extraUrlParams المعلمات الإضافية التي سيتم إلحاقها بسلسلة طلبات البحث لعنوان URL للطلب عبر اصطلاح "&foo=baz" العادي.

يضيف النموذج amp-analytics معلمة cd1 إضافية إلى الطلب ويعيّن قيمة المعلمة على "AMP":

"extraUrlParams": {
  "cd1": "AMP"
}

متى يتم إرسال البيانات: السمة triggers

تعطي السمة triggers وصفًا للوقت الذي ينبغي إرسال طلب تحليلات فيه. وهي تحتوي على زوج قيمة مفتاح يتمثل في اسم المشغل وتهيئة المشغل. يمكن أن يكون اسم المشغل أي سلسلة تتألف من حروف هجائية رقمية (a-zA-Z0-9).

على سبيل المثال، تتم تهيئة العنصر amp-analytics التالي لإرسال طلب إلى https://example.com/analytics عند تحميل المستند لأول مرة، وكلما تم النقر فوق علامة a:

"triggers": {
  "trackPageview": {
    "on": "visible",
    "request": "pageview"
  },
  "trackAnchorClicks": {
    "on": "click",
    "selector": "a",
    "request": "event",
    "vars": {
      "eventId": "42",
      "eventLabel": "clicked on a link"
    }
  }
}

تدعم AMP تهيئات المشغل التالية:

تهيئة المشغل الوصف
on (مطلوب) الحدث الذي سيتم توزيع الرسائل إليه. القيم الصالحة هي click، وscroll، وtimer، وvisible.
request (مطلوب) اسم الطلب الذي سيتم إرساله (على النحو المحدد في الطلبات).
vars كائن يحتوي على أزواج قيمة مفتاح للاستخدام في تجاوز vars المحدد في تهيئة المستوى الأعلى، أو لتحديد vars فريد لهذا المشغل (انظر أيضًا ترتيب استبدال المتغير).
selector (مطلوب عند تعيين on على click) محدّد CSS الذي يُستخدم لتحسين العناصر التي ينبغي تتبعها. استخدم القيمة * لتتبع كل العناصر. يتم استخدام هذه التهيئة بالتزامن مع المشغل click. تعرّف على كيفية استخدام المحدّد لتتبع النقرات على الصفحة وكذلك التفاعلات الاجتماعية.
scrollSpec (مطلوب عند تعيين on على scroll) عناصر التحكم التي يتم تنشيط الحدث scroll بموجب شروطها عند التمرير عبر الصفحة. يمكن أن يحتوي هذا الكائن على verticalBoundaries وhorizontalBoundaries. واحدة من الخصيصتين على الأقل مطلوبة لتنشيط حدث scroll. يجب أن تكون قيم كلّ من الخصيصتين صفائف من الأرقام التي تحتوي على حدود يتم إنشاء حدث تمرير فيها. انظر هذا النموذج في تتبع التمرير.
timerSpec (مطلوب عند تعيين on على timer) عناصر التحكم عند تنشيط الحدث timer. سيتم تشغيل المؤقّت في الحال، وبعد ذلك عند فاصل زمني محدد. يتم استخدام هذه التهيئة بالتزامن مع المشغل timer.

مهم: يتم تجاوز المشغلات المأخوذة من تهيئة ذات أسبقية أقل عبر المشغلات التي تحمل الأسماء نفسها والمأخوذة من تهيئة ذات أسبقية أعلى (انظر ترتيب استبدال المتغير.

كيفية إرسال البيانات: السمة transport

تحدد السمة transport كيفية إرسال طلب. ويتم تمكين الأساليب الثلاثة التالية افتراضيًا:

أسلوب النقل الوصف
beacon يشير إلى إمكانية استخدام navigator.sendBeacon لإرسال الطلب. سيرسل هذا طلب POST مع بيانات اعتماد ونص فارغ.
xhrpost يشير إلى إمكانية استخدام XMLHttpRequest لإرسال الطلب. سيرسل هذا طلب POST مع بيانات اعتماد ونص فارغ.
image يشير إلى إمكانية إرسال الطلب عبر إنشاء علامة Image. سيرسل هذا طلب GET.

يتم استخدام أسلوب نقل واحد فقط، وهو الأسلوب الذي يتميز بالأسبقية الأعلى التي يتم تمكينها والسماح بها وتوفيرها. هذه الأسبقية هي beacon > xhrpost > image. إذا كان وكيل مستخدم البرنامج لا يدعم أسلوبًا معينًا، فسوف يتم استخدام الأسلوب الممكّن التالي من علو الأسبقية.

اجعل السمة transport ضمن تهيئتك في حالة واحدة وهي إذا أردت تحديد خيارات النقل، وإلا، فقد تتسبب في إيقاف الطلبات.

في النموذج أدناه، يكون beacon وxhrpost معينين إلى false، لذا لن يتم استخدامهما حتى إذا كانت أسبقيتهما أعلى من image. إذا كان وكيل مستخدم البرنامج يدعم الأسلوب image، فسوف يتم استخدامه؛ وإلا، فلن يتم إرسال أي طلب.

'transport': {
  'beacon': false,
  'xhrpost': false,
  'image': true
}

ترتيب استبدال المتغير

تملأ AMP المتغيرات بالقيم بترتيب يستند إلى الأسبقية:

  1. التهيئات البعيدة (عبر config).
  2. تكون vars مضمّنة داخل مشغل ضمن triggers.
  3. تكون vars - عند المستوى الأعلى - مضمّنة ضمن amp-analytics.
  4. القيم المقدّمة بواسط النظام الأساسي.

في هذا النموذج، توجد تهيئة بعيدة، وهي عبارة عن متغيرات محددة عند المستوى الأعلى، وفي المشغلات، وعند مستوى النظام الأساسي:

<amp-analytics config="http://example.com/config.json">
<script type="application/json">
{
  "requests": {
    "pageview": "https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}&clientId=${clientId(cid-scope)}",
  },
  "vars": {
    "account": "ABC123",
    "title": "Homepage"
  },
  "triggers": {
    "some-event": {
      "on": "visible",
      "request": "pageview",
      "vars": {
        "title": "My homepage",
        "clientId": "my user"
      }
  }
}
</script>
</amp-analytics>

عند تحديد var نفسه في مواقع عديدة، يعيّن ترتيب الأسبقية للمتغير قيمته مرة واحدة. ولذلك، إذا تم تحديد account بواسطة التهيئة البعيدة بوصفه UA-XXXXX-Y في النموذج أعلاه، فسوف تكون قيم العديد من المتغيرات كما يلي:

var القيمة يتم تحديدها بواسطة
canonicalUrl http://example.com/path/to/the/page النظام الأساسي
title الصفحة الرئيسية الخاصة بي المشغل
account UA-XXXXX-Y التهيئة البعيدة
clientId my user المشغل