حالات الاستخدام المتقدّمة

يصف هذا المستند الميزات المتقدمة من الإصدار 4 من Google Analytics Reporting API. للحصول على مرجع مفصّل لواجهة برمجة التطبيقات، يمكنك الاطّلاع على الدليل المرجعي.

مقدمة

بعد إنشاء تقرير بسيط، استخدِم الميزات التالية لإنشاء تقارير متقدمة:

النقاط المحورية

يتيح لك الإصدار 4 من Google Analytics Reporting API إنشاء جداول محورية. لإنشاء طلب باستخدام جدول محوري، حدِّد الحقل محور في ReportRequest. يحتوي العنصر محوري على مجموعته الخاصة من السمات والمقاييس، بالإضافة إلى الميزات الاختيارية startGroup وmaxGroupCount لتحديد عدد السمات التي سيتم تضمينها في الجدول المحوري.

الطلب

يطلب طلب بيانات من واجهة برمجة التطبيقات التالي الجلسات حسب البلد وعرض النتائج على المتصفّح:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dateRanges":
      [
        {
          "startDate": "2014-11-01",
          "endDate": "2014-11-30"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:sessions"
        }
      ],
      "dimensions":
      [
        {
          "name": "ga:country"
        }
      ],
      "pivots":
      [
        {
          "dimensions":
          [
            {
              "name": "ga:browser"
            }
          ],
          "maxGroupCount": 3,
          "startGroup": 3,
          "metrics":
          [
            {
              "expression": "ga:sessions"
            }
          ]
        }
      ]
    }
  ]
}

عنوان عمود الاستجابة

في كائن report الذي يتم عرضه لطلب محوري، يحتوي metricHeader على قائمة بكائنات pivotHeaders التي تحدد حقولها pivotHeaderEntries ترتيب قيم السمات المحورية وقيم المقاييس المقابلة لها، على سبيل المثال:

"columnHeader": {
    "dimensions": [
        "ga:country"
    ],
    "metricHeader": {
        "metricHeaderEntries": [
            {
                "name": "ga:sessions",
                "type": "INTEGER"
            }
        ],
        "pivotHeaders": [
            {
                "pivotHeaderEntries": [
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Internet Explorer"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    },
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Firefox"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    },
                    {
                        "dimensionNames": [
                            "ga:browser"
                        ],
                        "dimensionValues": [
                            "Android Browser"
                        ],
                        "metric": {
                            "name": "ga:sessions",
                            "type": "INTEGER"
                        }
                    }
                ],
                "totalPivotGroupsCount": 7
            }
        ]
    }
},

صفوف الردود

ويحدد كل صف من كائنات reportData صفيفًا من كائنات dateRangeValue، ويحتوي كل صف منها على مجموعة من كائنات pivotValue، ويتوافق ترتيب القيم مع ترتيب المقاييس المدرجة في العناوين المحورية في رأس عمود الاستجابة.

"rows": [
    ...
    {
        "dimensions": [
            "United States"
        ],
        "metrics": [
            {
                "pivotValues": [
                    {
                        "values": [
                            "21",
                            "18",
                            "1"
                        ]
                    }
                ],
                "values": [
                    "192"
                ]
            }
        ]
    }
],

تجدر الإشارة إلى أنّ هناك ثلاث قيم محورية فقط في التقرير لأنّه في الطلب الأصلي، تكون قيمة maxGroupCount هي 3. قد يصل عدد القيم إلى سبع قيم بسبب السمة "totalPivotGroupsCount": 7.

مثال على صف الجدول المحوري

في نموذج الرد أعلاه، يتم تمثيل الصف المرتبط ببلد الولايات المتحدة في الجدول المحوري التالي:

البلد إجمالي
جلسة
جلسة في Internet Explorer
جلسات في FireFox		 جلسات
في متصفّح Android
الهند 12 3 2 4
الولايات المتحدة 192 21 18 1
المملكة المتحدة 35 12 2 0

المجموعات النموذجية

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

لتحديد طلب مجموعة نموذجية، يجب تحديد عنصر مجموعة نموذجية باستخدام name وtype وdateRange:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions":
      [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthDay"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:cohortActiveUsers"
        },
        {
          "expression": "ga:cohortTotalUsers"
        }
      ],
      "cohortGroup":
      {
        "cohorts":
        [
          {
            "name": "cohort 1",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-08-01",
              "endDate": "2015-08-01"
            }
          },
          {
            "name": "cohort 2",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-07-01",
              "endDate": "2015-07-01"
            }
          }
        ]
      }
    }
  ]
}

راجِع المثال أعلاه في مستكشف واجهات برمجة التطبيقات.

القيود المفروضة على المجموعات النموذجية

يجب أن يستوفي طلب مجموعة نموذجية صالح القيود التالية:

  • لا يتمّ تضمين السمة ga:cohort إلا إذا كان الطلب يتضمّن تعريفًا واحدًا أو أكثر من تعريفات المجموعة النموذجية.
  • يجب أن يكون اسم المجموعة النموذجية فريدًا.
  • يبلغ الحد الأقصى لعدد المجموعات النموذجية في الطلب 12 مجموعة.
  • إذا تم تحديد ga:cohortNthWeek، يجب أن يكون تاريخ البدء الأحد ويجب أن يكون تاريخ الانتهاء السبت. إذا تم تحديد ga:cohortNthMonth، يجب أن يكون تاريخ البدء هو اليوم الأول من الشهر وأن يكون تاريخ الانتهاء هو آخر يوم في الشهر. إذا تم تحديد ga:cohortNthDay، يجب أن يكون النطاق الزمني يومًا واحدًا بالضبط.
  • لا يُسمح بطلبات المجموعات النموذجية التي لها تاريخ اليوم.
  • يجب ألا تكون طلبات المجموعات النموذجية وطلبات غير المجموعات النموذجية في طلب batchGet نفسه.
  • يجب أن يكون النطاق الزمني في المجموعات النموذجية بعد 1 شباط (فبراير) 2015.

القيمة الدائمة

يوضِّح تقرير "القيمة الدائمة" كيفية نمو قيمة المستخدِم (الأرباح) والتفاعل (مرّات مشاهدة التطبيق والأهداف المكتملة والجلسات ومدة الجلسة) خلال 90 يومًا بعد اكتساب المستخدِم. الاطّلاع على السمات والمقاييس المحدّدة للقيمة الدائمة

يتم تعريف طلب القيمة الدائمة على أنّه مجموعة نموذجية مع ضبط الحقل lifetimeValue على true، على سبيل المثال:

POST https://analyticsreporting.googleapis.com/v4/reports:batchGet
{
  "reportRequests":
  [
    {
      "viewId": "XXXX",
      "dimensions":
      [
        {
          "name": "ga:cohort"
        },
        {
          "name": "ga:cohortNthWeek"
        }
      ],
      "metrics":
      [
        {
          "expression": "ga:cohortTotalUsersWithLifetimeCriteria"
        },
        {
          "expression": "ga:cohortRevenuePerUser"
        }
      ],
      "cohortGroup":
      {
        "cohorts":
        [
          {
            "name": "cohort 1",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-08-01",
              "endDate": "2015-09-01"
            }
          },
          {
            "name": "cohort 2",
            "type": "FIRST_VISIT_DATE",
            "dateRange":
            {
              "startDate": "2015-07-01",
              "endDate": "2015-08-01"
            }
          }
        ],
        "lifetimeValue": true
      }
    }
  ]
}

راجِع المثال أعلاه في مستكشف واجهات برمجة التطبيقات.

سمات ومقاييس المجموعة النموذجية والقيمة الدائمة

الأبعاد

اسم السمة التعريف
ga:cohort اسم المجموعة النموذجية التي ينتمي إليها المستخدم. واستنادًا إلى كيفية تحديد المجموعات النموذجية، يمكن أن ينتمي المستخدم إلى مجموعات نموذجية متعددة، على غرار الطريقة التي يمكن أن ينتمي بها المستخدم إلى شرائح متعددة.
ga:cohortNthDay معادلة يوم مستندة إلى 0 بالنسبة إلى تاريخ تعريف المجموعة النموذجية. على سبيل المثال، إذا تم تحديد مجموعة نموذجية بتاريخ أول زيارة على أنّه 2015-09-01، ستكون قيمة ga:cohortNthDay 3 في التاريخ 2015-09-04.
ga:cohortNthMonth معادلة الشهر المستندة إلى 0 بالنسبة إلى تاريخ تعريف المجموعة النموذجية.
ga:cohortNthWeek معادلة الأسبوع المستندة إلى القيمة 0 بالنسبة إلى تاريخ تعريف المجموعة النموذجية.
ga:acquisitionTrafficChannel قناة الزيارات التي تم اكتساب المستخدم من خلالها. ويتم استخراجه من الجلسة الأولى للمستخدم. يتم احتساب قناة الزيارات استنادًا إلى القواعد التلقائية لتصنيف القنوات إلى مجموعات (على مستوى الملف الشخصي، إن توفّر) في وقت اكتساب المستخدِمين.
ga:acquisitionSource المصدر الذي تم اكتساب المستخدم من خلاله. المستمدة من الجلسة الأولى للمستخدِم.
ga:acquisitionMedium الوسيط الذي تم اكتساب المستخدِم من خلاله. المستمدة من الجلسة الأولى للمستخدِم.
ga:acquisitionSourceMedium القيمة المجمّعة لـ ga:userAcquisitionSource وga:acquisitionMedium.
ga:acquisitionCampaign الحملة التي تم اكتساب المستخدم من خلالها. المستمدة من الجلسة الأولى للمستخدِم.

المقاييس

اسم المقياس التعريف
ga:cohortActiveUsers يكون هذا المقياس ملائمًا في سياق سمات الإزاحة المستنِدة إلى القيمة 0 (ga:cohortNthDay أو ga:cohortNthWeek أو ga:cohortNthMonth). يشير إلى عدد المستخدِمين في المجموعة النموذجية النشطين في الفترة الزمنية المقابلة لليوم/الأسبوع/الشهر في المجموعة النموذجية. على سبيل المثال، بالنسبة إلى ga:cohortNthWeek = 1، عدد المستخدمين (في المجموعة النموذجية) النشطين في الأسبوع الثاني. إذا كان الطلب لا يتضمّن أيًا من ga:cohortNthDay أو ga:cohortNthWeek أو ga:cohortNthMonth، سيكون لهذا المقياس القيمة نفسها المُستخدَمة في ga:cohortTotalUsers.
ga:cohortTotalUsers عدد المستخدمين الذين ينتمون إلى المجموعة النموذجية، ويُعرف أيضًا باسم حجم المجموعة النموذجية.
ga:cohortAppviewsPerUser مرات مشاهدة التطبيق لكل مستخدم في مجموعة نموذجية.
ga:cohortGoalCompletionsPerUser الأهداف المكتملة لكل مستخدم في مجموعة نموذجية.
ga:cohortPageviewsPerUser مرات مشاهدة الصفحة على الويب لكل مستخدم في المجموعة النموذجية
ga:cohortRetentionRate معدل الاحتفاظ بالمجموعة النموذجية.
ga:cohortRevenuePerUser الأرباح من كل مستخدم في المجموعة النموذجية.
ga:cohortVisitDurationPerUser مدّة الجلسة لكلّ مستخدِم في مجموعة نموذجية.
ga:cohortSessionsPerUser عدد الجلسات لكل مستخدم في مجموعة نموذجية.

مقاييس القيمة الدائمة

اسم المقياس التعريف
ga:cohortTotalUsersWithLifetimeCriteria ويكون هذا الأمر ملائمًا في سياق طلب يتضمّن السمات ga:acquisitionTrafficChannel أو ga:acquisitionSource أو ga:acquisitionMedium أو ga:acquisitionCampaign. ويمثّل ذلك عدد المستخدِمين في المجموعات النموذجية الذين تمّ اكتسابهم من خلال القناة أو المصدر أو الوسيط أو الحملة الحالية. على سبيل المثال، بالنسبة إلى ga:acquisitionTrafficChannel=Direct، يمثّل ذلك عدد المستخدِمين في المجموعة النموذجية الذين تم اكتسابهم مباشرةً. في حال عدم توفُّر أي من السمات المذكورة، تساوي قيمتها ga:cohortTotalUsers (مشاهدات التطبيق فقط).
ga:cohortAppviewsPerUserWithLifetimeCriteria مرات مشاهدة التطبيق لكل مستخدم لسمة الاكتساب في مجموعة نموذجية (مشاهدات التطبيق فقط).
ga:cohortGoalCompletionsPerUserWithLifetimeCriteria الأهداف المكتملة لكل مستخدم لسمة الاكتساب في مجموعة نموذجية (مرّات مشاهدة التطبيق فقط).
ga:cohortPageviewsPerUserWithLifetimeCriteria مرات مشاهدة الصفحة على الويب لكل مستخدم لسمة الاكتساب في مجموعة نموذجية (مشاهدات التطبيق فقط).
ga:cohortRevenuePerUserWithLifetimeCriteria الأرباح من كل مستخدم لسمة الاكتساب في مجموعة نموذجية (مرّات مشاهدة التطبيق فقط).
ga:cohortSessionsPerUserWithLifetimeCriteria مدّة الجلسة لكلّ مستخدِم لسمة الاكتساب في مجموعة نموذجية (مرّات مشاهدة التطبيق فقط).