موارد استفاده پیشرفته

این سند چندین ویژگی پیشرفته از API داده گوگل آنالیتیکس نسخه ۱ را شرح می‌دهد. برای مرجع دقیق API، به مرجع API مراجعه کنید.

فهرست کردن تعاریف سفارشی و ایجاد گزارش‌ها

API داده می‌تواند گزارش‌هایی در مورد ابعاد سفارشی ثبت‌شده و معیارهای سفارشی ایجاد کند. متد API فراداده می‌تواند برای فهرست کردن نام‌های API تعاریف سفارشی ثبت‌شده‌ی Property شما استفاده شود. این نام‌های API را می‌توان در درخواست‌های گزارش به متد runReport به عنوان مثال استفاده کرد.

بخش‌های زیر مثال‌هایی برای هر نوع تعریف سفارشی نشان می‌دهند. در این مثال‌ها، GA_PROPERTY_ID را با شناسه ویژگی خود جایگزین کنید.

ابعاد سفارشی رویداد-محدود

مرحله ۱: متد API متادیتا را با شناسه ویژگی خود جستجو کنید.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

مرحله ۲: بُعد سفارشیِ Event-Scoped که می‌خواهید از پاسخ، گزارش‌هایی روی آن ایجاد کنید را پیدا کنید. اگر بُعد مورد نظر وجود ندارد، باید آن بُعد را ثبت کنید .

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

مرحله ۳: بُعد سفارشی را در درخواست گزارش وارد کنید. در زیر یک نمونه درخواست به متد runReport آمده است.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

ابعاد سفارشی کاربر-محدوده

مرحله ۱: متد API متادیتا را با شناسه ویژگی خود جستجو کنید.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

مرحله ۲: بُعد سفارشیِ مورد نظر کاربر که می‌خواهید گزارش‌هایی از پاسخ روی آن ایجاد کنید را پیدا کنید. اگر بُعد مورد نظر وجود ندارد، باید آن بُعد را ثبت کنید .

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

مرحله ۳: بُعد سفارشی را در درخواست گزارش وارد کنید. در زیر یک نمونه درخواست به متد runReport آمده است.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

معیارهای سفارشی مبتنی بر رویداد

مرحله ۱: متد API متادیتا را با شناسه ویژگی خود جستجو کنید.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

مرحله ۲: معیار سفارشی Event-Scoped مورد نظر خود را برای ایجاد گزارش از پاسخ پیدا کنید. اگر معیار مورد نظر وجود ندارد، باید آن را ثبت کنید .

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

مرحله ۳: معیار سفارشی را در درخواست گزارش وارد کنید. در زیر یک نمونه درخواست به متد runReport آمده است.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

معیارهای نرخ رویداد کلیدی برای یک رویداد کلیدی

مرحله ۱: متد API متادیتا را با شناسه ویژگی خود جستجو کنید.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

مرحله ۲: معیار نرخ رویداد کلیدی را برای یک رویداد کلیدی که علاقه‌مند به ایجاد گزارش از پاسخ آن هستید، پیدا کنید. اگر رویداد کلیدی وجود ندارد، باید رویداد کلیدی را تنظیم کنید .

"metrics": [
...
    {
      "apiName": "sessionKeyEventRate:add_to_cart",
      "uiName": "Session key event rate for add_to_cart",
      "description": "The percentage of sessions in which a specific key event was triggered",
    },
...
],

مرحله ۳: معیار نرخ رویداد کلیدی را در درخواست گزارش وارد کنید. در زیر یک درخواست نمونه به متد runReport آمده است.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}

میانگین‌های متریک سفارشی در محدوده رویداد

مرحله ۱: متد API متادیتا را با شناسه ویژگی خود جستجو کنید.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

مرحله ۲: میانگین معیار سفارشیِ در محدوده رویداد (Event-Scoped) مورد نظر برای ایجاد گزارش از پاسخ را پیدا کنید. اگر معیار مورد نظر وجود ندارد، باید آن را ثبت کنید .

"metrics": [
...
    {
      "apiName": "averageCustomEvent:credits_spent",
      "uiName": "Average Credits Spent",
      "description": "The average of an event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

مرحله ۳: میانگین متریک سفارشی را در یک درخواست گزارش وارد کنید. در زیر یک درخواست نمونه به متد runReport آمده است.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

نمونه‌های گزارش گروهی

گزارش‌های Cohort یک سری زمانی از میزان ماندگاری کاربر برای هر گروه ایجاد می‌کند. برای مستندات دقیق هر فیلد API، به مرجع REST برای CohortSpec مراجعه کنید.

ایجاد گزارش گروهی

در اینجا یک نمونه گزارش گروهی آمده است که در آن:

• گروه، کاربرانی با تاریخ firstSessionDate برابر با 2020-12-01 هستند؛ این تاریخ توسط شیء cohorts پیکربندی می‌شود. ابعاد و معیارهای موجود در پاسخ گزارش، فقط بر اساس کاربران گروه خواهد بود.
• گزارش گروه، سه ستون را نشان می‌دهد؛ این ستون‌ها توسط اشیاء ابعاد و معیارها پیکربندی شده‌اند.
  • cohort بُعد، نام گروه است.
  • بُعد cohortNthDay تعداد روزها از 2020-12-01 است.
  • معیار cohortActiveUsers تعداد کاربرانی است که هنوز فعال هستند.
• شیء cohortsRange مشخص می‌کند که گزارش باید شامل داده‌های رویداد از 2020-12-01 تا 2020-12-06 برای این گروه باشد.
  • وقتی از جزئیات DAILY استفاده می‌شود، برای حفظ انسجام، استفاده از بُعد cohortNthDay توصیه می‌شود.

درخواست گزارش برای گروه:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "DAILY"
    }
  },
}

برای این درخواست، یک نمونه پاسخ گزارش به صورت زیر است:

{
  "dimensionHeaders": [
    { "name": "cohort" }, { "name": "cohortNthDay" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "293" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "143" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "123" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "92" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
      "metricValues": [{ "value": "86" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "83" }]
    }
  ],
  "metadata": {},
  "rowCount": 6
}

از این پاسخ به گزارش، نموداری برای این گزارش کوهورت در ادامه آمده است. نکته قابل توجه در این گزارش این است که بیشترین کاهش کاربران فعال برای این گروه بین روز اول و دوم است.

گروه‌های چندگانه و درصد ماندگاری کاربر

جذب و حفظ کاربر، راه‌هایی برای رشد وب‌سایت یا اپلیکیشن شما هستند. گزارش‌های Cohort بر حفظ کاربر تمرکز دارند. در این مثال، گزارش نشان می‌دهد که این ملک، در طول دو هفته، 10 درصد بهبود در حفظ کاربر 4 روزه خود داشته است.

برای ایجاد این گزارش، سه گروه را مشخص می‌کنیم: گروه اول با firstSessionDate برابر با 2020-11-02 ، گروه دوم با firstSessionDate برابر با 2020-11-09 و گروه سوم با firstSessionDate برابر با 2020-11-16 . از آنجا که تعداد کاربران سایت شما برای این سه روز متفاوت خواهد بود، به جای استفاده از معیار مستقیم cohortActiveUsers ، معیار نسبت ماندگاری کاربر گروه را که cohortActiveUsers/cohortTotalUsers است، مقایسه می‌کنیم.

درخواست گزارش برای این گروه‌ها عبارت است از:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metrics": [
    {
      "name": "cohortRetentionFraction",
      "expression": "cohortActiveUsers/cohortTotalUsers"
    }
  ],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
      }
    ],
    "cohortsRange": {
      "endOffset": 4,
      "granularity": "DAILY"
    }
  },
}

برای این درخواست، یک نمونه پاسخ گزارش به صورت زیر است:

{
  "dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metricHeaders": [{
      "name": "cohortRetentionFraction",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.308" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.272" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.257" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.248" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.235" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.211" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.198" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.172" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.167" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.155" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.141" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.118" }]
    }
  ],
  "metadata": {},
  "rowCount": 15
}

از این پاسخ گزارش، نموداری برای این گزارش کوهورت به دست می‌آید. نکته‌ای که از این گزارش می‌توان دریافت این است که نرخ حفظ کاربر ۴ روزه در طول دو هفته ۱۰ درصد افزایش یافته است. گروه بعدی با firstSessionDate 2020-11-16 از نرخ حفظ کاربر گروه قبلی با firstSessionDate 2020-11-02 بیشتر است.

گروه‌های هفتگی و استفاده از گروه‌های دیگر با سایر ویژگی‌های API

برای حذف واریانس روزانه در رفتار کاربر، از گروه‌های هفتگی استفاده کنید. در گزارش‌های هفتگی گروه، همه کاربرانی که firstSessionDate در یک هفته دارند، گروه را تشکیل می‌دهند. هفته‌ها از یکشنبه شروع می‌شوند و شنبه پایان می‌یابند. همچنین در این گزارش، ما گروه را برش می‌دهیم تا کاربرانی را که در روسیه فعالیت دارند با کاربرانی که در مکزیک فعالیت دارند مقایسه کنیم. این برش از بُعد country و یک dimensionFilter برای در نظر گرفتن فقط دو کشور استفاده می‌کند.

درخواست گزارش برای این گروه‌ها عبارت است از:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "inListFilter": {
        "values": [ "Russia", "Mexico" ]
      }
    }
  },
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": {
          "startDate": "2020-10-04",
          "endDate": "2020-10-10"
        }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "WEEKLY"
    }
  },
}

برای این درخواست، یک نمونه پاسخ گزارش به صورت زیر است:

{
  "dimensionHeaders": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "105" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "98" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "35" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "24" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "23" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "17" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "3" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    }
  ],
  "metadata": {},
  "rowCount": 11
}

از این پاسخ به گزارش، نموداری از این گزارش کوهورت در ادامه آمده است. بر اساس این گزارش، این ملک در حفظ کاربرانی که در مکزیک فعالیت دارند، نسبت به کاربرانی که در روسیه فعالیت دارند، عملکرد بهتری دارد.

مقایسه‌ها

مقایسه‌ها به شما امکان می‌دهند زیرمجموعه‌هایی از داده‌های خود را در کنار هم ارزیابی کنید. می‌توانید با مشخص کردن فیلد comparisons در تعریف گزارش، مقایسه‌ها را تعریف کنید. ویژگی مقایسه‌ها در Data API مشابه مقایسه‌ها در رابط کاربری گوگل آنالیتیکس است.

برای مستندات دقیق هر فیلد API، به مرجع REST برای Comparison مراجعه کنید.

ایجاد یک مقایسه

شما می‌توانید برای هر مجموعه داده‌ای که می‌خواهید مقایسه کنید، یک مقایسه جداگانه ایجاد کنید. برای مثال، برای مقایسه داده‌های برنامه و وب، می‌توانید یک مقایسه برای داده‌های اندروید و iOS و یک مقایسه دیگر برای داده‌های وب ایجاد کنید.

در اینجا یک گزارش نمونه وجود دارد که دو مقایسه را تعریف می‌کند و کاربران فعال را بر اساس کشور تفکیک شده، ارائه می‌دهد.

اولین مقایسه با نام "ترافیک اپلیکیشن" از inListFilter برای تطبیق بُعد platform با مقادیر "iOS" و "Android" استفاده می‌کند. مقایسه دوم با نام "ترافیک وب" از stringFilter برای تطبیق بُعد platform با "web" استفاده می‌کند.

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
  {
    "comparisons": [
      {
        "name": "App traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "inListFilter": {
              "values": [
                "iOS",
                "Android"
              ]
            }
          }
        }
      },
      {
        "name": "Web traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "stringFilter": {
              "matchType": "EXACT",
              "value": "web"
            }
          }
        }
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ],
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  }

برای تمام درخواست‌هایی که از ویژگی مقایسه استفاده می‌کنند، فیلد comparison به طور خودکار به گزارش تولید شده اضافه می‌شود. این فیلد شامل نام مقایسه ارائه شده در درخواست است.

در اینجا نمونه‌ای از یک پاسخ حاوی مقایسه‌ها آمده است:

{
  "dimensionHeaders": [
    {
      "name": "comparison"
    },
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "638572"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "Japan"
        }
      ],
      "metricValues": [
        {
          "value": "376578"
        }
      ]
    },
  {
      "dimensionValues": [
        {
          "value": "App traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "79527"
        }
      ]
    },

    ...

  ],

...

}