API الرؤى

يمكن توفير واجهة واحدة وثابتة لاسترجاع إحصاءات الإعلانات.

• التقسيمات - نتائج المجموعة
• تقسيمات الإجراءات - يمكن فهم الاستجابة من تقسيمات الإجراءات.
• الوظائف غير المتزامنة - بالنسبة للطلبات ذات النتائج الكبيرة، يمكنك استخدام الوظائف غير المتزامنة
• التقييدات وأفضل الممارسات - تقييدات الاستدعاء والفلترة وأفضل الممارسات.

قبل أن تتمكّن من الحصول على البيانات المتعلقة بأداء إعلانك، يجب عليك إعداد إعلاناتك من أجل تتبع أدوات القياس التي تهتم بها. فيما يتعلق بذلك، يمكنك استخدام إشارات عنوان URL وبيكسل Meta وواجهة API التحويلات.

قبل البدء

ستحتاج إلى ما يلي:

• الإذن ads_read.
• تطبيق. راجع تطوير تطبيقات Meta لمزيد من المعلومات.

إحصاءات الحملة الإعلانية

للحصول على إحصاءات الأداء خلال آخر 7 أيام من الحملة الإعلانية:

curl -G \
  -d "date_preset=last_7d" \
  -d "access_token=ACCESS_TOKEN" \
  "https://graph.facebook.com/API_VERSION/AD_CAMPAIGN_ID/insights"

لمعرفة المزيد، يمكنك الرجوع إلى مرجع رؤى الإعلانات.

إجراء الاستدعاءات

تتوفر واجهة API الرؤى كعنصر ربط في أي كائن إعلانات.

الطلب

يمكنك طلب حقول محددة بقائمة مفصولة بفاصلة في المعلمات fields. على سبيل المثال:

curl -G \
-d "fields=impressions" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"
    

الاستجابة

{
  "data": [
    {
      "impressions": "2466376",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

المستويات

يمكنك تجميع نتائج على مستوى كائن محدد. يؤدي ذلك إلى عدم تكرار البيانات تلقائيًا.

الطلب

على سبيل المثال، يمكنك الحصول على رؤى حملة إعلانية على مستوى الإعلان.

curl -G \
-d "level=ad" \
-d "fields=impressions,ad_id" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/CAMPAIGN_ID/insights"

الاستجابة

{
  "data": [
    {
      "impressions": "9708",
      "ad_id": "6142546123068",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "impressions": "18841",
      "ad_id": "6142546117828",
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

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

نوافذ الإسناد

توفر نافذة إسناد التحويل إطارات زمنية تحدد متي يتم إسناد حدث معين لإعلان ما في تطبيق Meta. لمعرفة المعلومات الأساسية، يمكنك الرجوع إلى مركز مساعدة الأعمال من Meta، نبذة عن فترات الإسناد. يتم قياس الإجراءات التي تحدث عند بدء حدث تحويل ونأخذ في الاعتبار الفترة السابقة بمدة يوم واحد و7 أيام. ولعرض الإجراءات التي يتم إسنادها إلى فترات إسناد مختلفة، يمكنك تقديم طلب إلى /{ad-account-id}/insights. وإذا لم توفر action_attribution_windows، فسنستخدم الفترة 7d_click ونوفرها ضمن الحقل value.

فعلى سبيل المثال، حدد action_attribution_windows مع جعل القيمة 'value' ثابتة عند فترة الإسناد 7d_click. وقدّم طلبًا إلى act_10151816772662695/insights?action_attribution_windows=['1d_click','1d_view'] وستحصل على النتيجة التالية:

"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608,
"1d_view": 86,
"1d_click": 6510
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344,
"1d_view": 27.354069767442,
"1d_click": 0.36135944700461
},

// if attribution window is _not_ specified in query. And note that the number under 'value' key is the same even if attribution window is specified.
// act_10151816772662695/insights
"spend": 2352.45,
"actions": [
{
"action_type": "link_click",
"value": 6608
},
"cost_per_action_type": [
{
"action_type": "link_click",
"value": 0.35600030266344
},

توسيع الحقل

يمكنك طلب الحقول على مستوى العقدة وحسب الحقول المحددة في توسيع الحقل.

الطلب

curl -G \
-d "fields=insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_ID"

الاستجابة

{
  "id": "6042542123268",
  "name": "My Website Clicks Ad",
  "insights": {
    "data": [
      {
        "impressions": "9708",
        "date_start": "2016-03-06",
        "date_stop": "2016-04-01"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

الفرز

يمكنك فرز النتائج من خلال تقديم المعلمة sort مع {fieldname}_descending أو {fieldname}_ascending:

الطلب

curl -G \
-d "sort=reach_descending" \
-d "level=ad" \
-d "fields=reach" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID/insights"

الاستجابة

{
  "data": [
    {
      "reach": 10742,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-01"
    },
    {
      "reach": 5630,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-03"
    },
    {
      "reach": 3231,
      "date_start": "2009-03-28",
      "date_stop": "2016-04-02"
    },
    {
      "reach": 936,
      "date_start": "2009-03-29",
      "date_stop": "2016-04-02"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MQZDZD"
    }
  }
}

تصنيفات الإعلانات

إحصاءات لكل التصنيفات التي تتطابق أسماؤها. يتم تجميع هذه الإحصاءات في قيمة واحدة على مستوى كائن الإعلان. راجع مرجع تصنيفات الإعلانات لمزيد من المعلومات.

الطلب

curl -G \  
-d "fields=id,name,insights{unique_clicks,cpm,total_actions}" \
-d "level=ad" \
-d 'filtering=[{"field":"ad.adlabels","operator":"ANY", "value":["Label Name"]}]'  \
-d 'time_range={"since":"2015-03-01","until":"2015-03-31"}' \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_OBJECT_ID/insights"

الاستجابة

{
  "data": [
    {
      "unique_clicks": 74,
      "cpm": 0.81081081081081,
      "total_actions": 49,
      "date_start": "2015-03-01",
      "date_stop": "2015-03-31",
    },
  ], 
  "paging": {
    "cursors": {
      "before": "MA==",
      "after": "MA==",
    }
  }
}

تعريف النقرات

لفهم أدوات قياس أنواع النقرات التي توفرها Meta حاليًا بشكل أفضل، يُرجى قراءة التعريفات وطريقة استخدام كل نوع فيما يلي:

• النقرات على الروابط، actions:link_click - عدد النقرات على روابط الإعلانات لوجهات أو تجارب محددة، داخل الأصول المملوكة بواسطة Meta أو خارجها. يمكنك الرجوع إلى مركز مساعدة الإعلانات، النقرات على الروابط

• النقرات (الكل)، clicks - تحسب أداة القياس عدة أنواع من النقرات على إعلانك، بما في ذلك أنواع معينة من التفاعلات مع حاوية الإعلان والروابط التي تنقلك إلى وجهات أخرى والروابط التي تنقلك إلى تجارب إعلانية موسّعة. ويمكنك الرجوع إلى مركز مساعدة الإعلانات، النقرات (الكل)

الكائنات المحذوفة والمؤرشفة

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

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

يمكنك الحصول على إحصاءات الكائنات بالحالة ARCHIVED من العُقد الأصل الخاصة بها من خلال توفير معلمة filtering إضافية.

الطلب

للحصول على إحصاءات كل الإعلانات بالحالة ARCHIVED في حساب إعلاني مُدرج في قائمة واحدًا تلو الآخر:

curl -G \
  -d "level=ad" \
  -d "filtering=[{'field':'ad.effective_status','operator':'IN','value':['ARCHIVED']}]" \
  -d "access_token=<ACCESS_TOKEN>" \
  "https://graph.facebook.com/v19.0/act_<AD_ACCOUNT_ID>/insights/"

الاستجابة

لاحظ أن هذه الاستجابة تقوم بإرجاع الكائنات المؤرشفة فقط.

{
  "data": [
    {
      "impressions": "1741",
      "date_start": "2016-03-11",
      "date_stop": "2016-03-12"
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MAZDZD"
    }
  }
}

رؤى الكائنات المحذوفة

يمكنك الاستعلام عن رؤى الكائنات المحذوفة في حالة توفير المعرفات الخاصة بها أو باستخدام الفلتر ad.effective_status.

الطلب

على سبيل المثال، إذا كان لديك معرف المجموعة الإعلانية:

curl -G \
-d "fields=id,name,status,insights{impressions}" \
-d "access_token=ACCESS_TOKEN" \
"https://graph.facebook.com/v19.0/AD_SET_ID"
    

ففي هذا المثال، نستعلم بالحالة ad.effective_status:

POST https://graph.facebook.com/<VERSION>/act_ID/insights?access_token=token&appsecret_proof=proof&fields=ad_id,impressions&date_preset=lifetime&level=ad&filtering=[{"field":"ad.effective_status","operator":"IN","value":["DELETED"]}]

الاستجابة

{
  "id": "6042147342661",
  "name": "My Like Campaign",
  "status": "DELETED",
  "insights": {
    "data": [
      {
        "impressions": "1741",
        "date_start": "2016-03-11",
        "date_stop": "2016-03-12"
      }
    ],
    "paging": {
      "cursors": {
        "before": "MAZDZD",
        "after": "MAZDZD"
      }
    }
  }
}

استكشاف الأخطاء وإصلاحها

حالات انتهاء المهلة

تتمثل المشكلات الشائعة التي تؤدي إلى حدوث فشل في نقطة النهاية هذه في تقديم طلبات أكثر من اللازم وانتهاء المهلة:

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

التوصيات

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

تقييد معدلات الاستدعاء

تستخدم API الرؤى من Meta تقييد معدلات الاستدعاء لضمان تجربة إعداد تقارير مثالية لكل شركائنا. لمزيد من المعلومات والاقتراحات، يمكنك الرجوع إلى التقييدات وأفضل الممارسات في API الرؤى.

التباين مع مدير الإعلانات

يختلف السلوك الافتراضي لـ API عن السلوك الافتراضي في مدير الإعلانات. إذا كنت ترغب في عرض السلوك ذاته مثل مدير الإعلانات، فيُرجى تعيين الحقل use_account_attribution_setting على true.

معرفة المزيد

• رؤى الحساب الإعلاني
• رؤى الحملة الإعلانية
• رؤى المجموعة الإعلانية
• رؤى الإعلان

لا تحتوي API هذه على أي نقاط نهاية غير مذكورة في القائمة أعلاه. إذا كنت تخطط لتضمين تقارير من Meta في الحل الذي توفره، فيمكنك الرجوع إلى شروط منصة Meta وسياسات المطوّرين في API التسويق.