رؤى مستخدم Instagram

تمثل أدوات قياس التفاعل على مواقع التواصل الاجتماعي لدى مستخدم Instagram.

الإنشاء

هذه العملية غير مدعومة.

القراءة

GET /{ig-user-id}/insights

يمكن إرجاع رؤى حول مستخدم IG.

التقييدات

• لا تتوفر أدوات القياس follower_count وonline_followers وaudience_* لدى مستخدمي IG بأقل من 100 متابع.
• تتوفر بيانات الرؤى حول أداة القياس online_followers لأخر 30 يومًا فقط.
• إذا كانت بيانات الرؤى التي تطلبها غير موجودة أو غير متوفرة حاليًا، فستعمل API على إرجاع مجموعة بيانات فارغة بدلاً من القيمة 0 بالنسبة لأدوات القياس الفردية.
• لا تعرض أدوات قياس المعلومات الديموغرافية سوى أفضل 45 جهة أداء (على سبيل المثال بالنسبة إلى audience_city، يمكن إرجاع ما يصل إلى 45 مدينة بأعلى عدد من المتابعين).
• يتم استخدام المشاهدين الذين لدينا بيانات ديموغرافية لهم فقط في حسابات أداة قياس المعلومات الديموغرافية.
• قد ينتج عن جمع قيم أداة قياس المعلومات الديموغرافية قيمة أقل من عدد المتابعين (راجع نقطة التعداد السابقة).
• لا تدعم أدوات القياسaudience_* معلمات النطاقsince وuntil.
• قد تتأخر البيانات المستخدمة لحساب أدوات القياس لمدة تصل إلى 48 ساعة.

المتطلبات

بنية الطلب

GET https://graph.facebook.com/{api-version}/{ig-user-id}/insights
  ?metric={metric}
  &period={period}
  &since={since}
  &until={until}
  &access_token={access-token}

معلمات المسار

معلمات سلسلة الاستعلام

أدوات القياس والفترات

سيكون لأدوات القياس التي تدعم فترات lifetime نتائج يتم إرجاعها في مصفوفة من فترات 24 ساعة، مع فترات تنتهي بتوقيات UTC -7:00. لا تدعم أدوات القياس audience_* معلمات النطاقsince وuntil.

النطاق

يدعم عنصر الربط هذا تقسيم الصفحات استنادًا إلى الوقت، لذا يمكنك تضمين المعلمتين since وuntil مع طوابع زمنية بتنسيق Unix من أجل تحديد نطاق. على سبيل المثال، للحصول على 28 يومًا من مرات ظهور الإعلانات — كل يوم خلال آخر 10 أيام — يمكنك إنشاء طوابع زمنية بتنسيق Unix لمدة 10 أيام سابقة واليوم الحالي، وتعيينها إلى المعلمتين since وuntil، وتضمينها في طلبك:

metric=impressions&period=days_28&since=1501545600&until=1502493720

تتسم المعلمتان since وuntil بأنهما شاملتان، لذا، إذا كان النطاق المتوفر لديك يتضمن يومًا لم ينته بعد (أي، اليوم الحالي)، فقد تقوم الاستعلامات اللاحقة التي يتم إجراؤها على مدار اليوم بإرجاع قيم متزايدة. وإذا لم يتم تضمين المعلمتين since وuntil، فسيتم تعيين واجهة API افتراضيًا إلى نطاق يستغرق يومين: من اليوم السابق حتى اليوم الحالي.

عينة من الطلب

curl -X GET \
  'https://graph.facebook.com/v19.0/17841405822304914/insights?metric=impressions,reach,profile_views&period=day&access_token=IGQVJ...'

عينة من الاستجابة

{
  "data": [
    {
      "name": "impressions",
      "period": "day",
      "values": [
        {
          "value": 4,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 66,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Impressions",
      "description": "Total number of times this profile has been seen",
      "id": "17841400008460056/insights/impressions/day"
    },
    {
      "name": "reach",
      "period": "day",
      "values": [
        {
          "value": 3,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 36,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Reach",
      "description": "Total number of unique accounts that have seen this profile",
      "id": "17841400008460056/insights/reach/day"
    },
    {
      "name": "profile_views",
      "period": "day",
      "values": [
        {
          "value": 0,
          "end_time": "2017-05-04T07:00:00+0000"
        },
        {
          "value": 2,
          "end_time": "2017-05-05T07:00:00+0000"
        }
      ],
      "title": "Profile Views",
      "description": "Total number of unique accounts that have viewed this profile within the specified period",
      "id": "17841400008460056/insights/profile_views/day"
    }
  ]
}

لاحظ أن عينة الطلب الواردة أعلاه لم تتضمن المعلمتين since وuntil، لذا قامت واجهة API بإرجاع البيانات لنطاق افتراضي يستغرق يومين. ويتم تحديد كل يوم بواسطة طابع زمني بتنسيق ISO 8601 وبتوقيت UTC بدون إزاحة والذي تم تعيينه إلى الخاصية end_time.

تشير الخاصية end_time إلى تاريخ إيقاف الرجوع لمجموعة البيانات بحيث لا يتم تضمين البيانات المتوفرة بتاريخ يسبق تاريخ هذه القيمة عند حساب مجموعة البيانات.

التحديث

هذه العملية غير مدعومة.

الحذف

هذه العملية غير مدعومة.

أدوات القياس الجديدة

بنية الطلب

GET https://graph.facebook.com/{api-version}/{ig-user-id}/insights
  ?metric={metric}
  &period={period}
  &timeframe={timeframe}
  &metric_type={metric-type}
  &breakdown={breakdown}
  &since={since}
  &until={until}
  &access_token={access-token}

معلمات المسار

معلمات سلسلة الاستعلام

التقسيم

إذا طلبت metric_type=total_value، فيمكنك أيضًا تحديد تقسيم واحد أو أكثر من تقسيم، وسيتم تقسيم النتائج إلى مجموعات أصغر حسب التقسيم المحدد. يمكن أن تكون القيم كما يلي:

• contact_button_type — تقسيم النتائج حسب مكون واجهة مستخدم الملف الشخصي الذي ضغط عليه المشاهدون أو نقروا عليه. يمكن أن تكون قيم الاستجابة كما يلي:

  • BOOK_NOW
  • CALL
  • DIRECTION
  • EMAIL
  • INSTANT_EXPERIENCE
  • TEXT
  • UNDEFINED
• follow_type — تقسيم النتائج حسب المتابعين أو غير المتابعين. يمكن أن تكون قيم الاستجابة كما يلي:

  • FOLLOWER
  • NON_FOLLOWER
  • UNKNOWN
• media_product_type — تقسيم النتائج حسب الوسيلة التي استخدمها المشاهدون لعرض وسائط مستخدم التطبيق أو التفاعل معها. يمكن أن تكون قيم الاستجابة كما يلي:

  • AD
  • FEED
  • REELS
  • STORY

يمكنك الرجوع إلى جدول أدوات القياس لتحديد أدوات القياس المتوافقة مع التقسيم. إذا طلبت أداة قياس لا تدعم التقسيم، فستعمل API على إرجاع خطأ ("An unknown error has occurred.")، لذلك توخ الحذر إذا كنت تطلب العديد من أدوات القياس ضمن استعلام واحد.

إذا طلبت metric_type=time_series، فلن يتم تضمين التقسيم في الاستجابة.

نوع أداة القياس

يمكنك تحديد الطريقة التي تريد تجميع النتائج بها، إما حسب الفترة الزمنية أو كإجمالي بسيط (مع التقسيمات، إذا كانت مطلوبة). يمكن أن تكون القيم كما يلي:

• time_series — يشير إلى API لبدء تجميع النتائج حسب الفترة الزمنية. راجع الفترة.
• total_value — يشير إلى API لبدء إرجاع النتائج كإجمالي بسيط. إذا تم تضمين التقسيمات في الطلب، فسيتم تقسيم مجموعة البيانات بشكل أوسع حسب التقسيمات المحددة. راجع التقسيم.

الفترة

تحدد لـ API الإطار الزمني الذي يجب استخدامه عند تجميع النتائج. ولا تتوافق إلا مع أدوات القياس المتعلقة بالتفاعل.

الإطار الزمني

يحدد لـ API نطاق البحث عن البيانات عند طلب أدوات القياس المتعلقة بالمعلومات الديموغرافية. تتجاوز هذه القيمة المعلمتين since وuntil.

النطاق

يمكن تعيين الطوابع الزمنية بتنسيق UNIX إلى المعلمتين since وuntil لتحديد النطاق. لن تتضمن API إلا البيانات التي تم إنشاؤها ضمن هذا النطاق (بشكل شامل). إذا لم يتم تضمين هذه المعلمات، فسيتم تعيين نطاق بحث API على آخر 24 ساعة سابقة.

بالنسبة إلى أدوات القياس المتعلقة بالمعلومات الديموغرافية، تتجاوز المعلمة timeframe هذه القيم. راجع الفترة الزمنية.

أدوات القياس

أدوات قياس التفاعل

أدوات قياس المعلومات الديموغرافية

الاستجابة

كائن بلغة JSON يحتوي على نتائج الاستعلام. يمكن أن تتضمن النتائج البيانات التالية، استنادًا إلى مواصفات الاستعلام:

{
  "data": [
    {
      "name": "{data}",
      "period": "{period}",
      "title": "{title}",
      "description": "{description}",
      "total_value": {
        "value": {value},
        "breakdowns": [
          {
            "dimension_keys": [
              "{key-1}",
              "{key-2",
              ...
            ],
            "results": [
              {
                "dimension_values": [
                  "{value-1}",
                  "{value-2}",
                  ...
                ],
                "value": {value},
                "end_time": "{end-time}"
              },
              ...
            ]
          }
        ]
      },
      "id": "{id}"
    }
  ],
  "paging": {
    "previous": "{previous}",
    "next": "{next}"
  }
}

محتوى الاستجابة

عينة من طلب أداة قياس التفاعل

curl -i -X GET \
  "https://graph.facebook.com/v19.0/17841405822304914/insights?metric=reach&period=day&breakdown=media_product_type&metric_type=total_value&since=1658991600&access_token=EAAOc..."

عينة من استجابة أداة قياس التفاعل

{
  "data": [
    {
      "name": "reach",
      "period": "day",
      "title": "Accounts reached",
      "description": "The number of unique accounts that have seen your content, at least once, including in ads. Content includes posts, stories, reels, videos and live videos. Reach is different from impressions, which may include multiple views of your content by the same accounts. This metric is estimated and in development.",
      "total_value": {
        "value": 224,
        "breakdowns": [
          {
            "dimension_keys": [
              "media_product_type"
            ],
            "results": [
              {
                "dimension_values": [
                  "CAROUSEL_CONTAINER"
                ],
                "value": 100
              },
              {
                "dimension_values": [
                  "POST"
                ],
                "value": 124
              }
            ]
          }
        ]
      },
      "id": "17841405309211844/insights/reach/day"
    }
  ],
  "paging": {
    "previous": "https://graph.face...",
    "next": "https://graph.face..."
  }

عينة من طلب أداة قياس المعلومات الديموغرافية

curl -i -X GET \
  "https://graph.facebook.com/v19.0/17841405822304914/insights?metric=engaged_audience_demographics&period=lifetime&timeframe=last_90_days&breakdowns=country&metric_type=total_value&access_token=EAAOc..."

عينة من استجابة أداة قياس المعلومات الديموغرافية

{
  "data": [
    {
      "name": "engaged_audience_demographics",
      "period": "lifetime",
      "title": "Engaged audience demographics",
      "description": "The demographic characteristics of the engaged audience, including countries, cities and gender distribution.",
      "total_value": {
        "breakdowns": [
          {
            "dimension_keys": [
              "timeframe",
              "country"
            ],
            "results": [
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "AR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "RU"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "MA"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "LA"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "IQ"
                ],
                "value": 2
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "MX"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "FR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "ES"
                ],
                "value": 3
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "NL"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "TR"
                ],
                "value": 1
              },
              {
                "dimension_values": [
                  "LAST_90_DAYS",
                  "US"
                ],
                "value": 7
              }
            ]
          }
        ]
      },
      "id": "17841401130346306/insights/engaged_audience_demographics/lifetime"
    }
  ]
}