تثبيت التطبيقات وإنشاء الرموز وتحديثها وإلغاؤها

نظرًا لأن مستخدم النظام يمثل استدعاءات الخادم، فإنه لا يتمتع بتسجيل دخول فيسبوك ولا يمكنه تثبيت تطبيق أو الخضوع لعملية دفق oAuth القياسي في فيسبوك لإنشاء رمز. يجب تنفيذ ذلك عبر استدعاءات API.

أنواع رموز وصول النظام

تثبيت التطبيقات

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

يجب أن ينتمي مستخدم النظام والتطبيق إلى مدير الأعمال نفسه. ولا يمكن تثبيت أي تطبيقات بخلاف تلك التطبيقات التي لديها وصول قياسي إلى واجهة API إدارة الإعلانات أو وصول أعلى.

لتثبيت تطبيق خاص بمسؤول نظام، تحتاج إلى:

• access_token: خاص بمستخدم مسؤول أو مستخدم نظام مسؤول أو مستخدم نظام آخر
• business_app: يمثل معرفًا من التطبيق الذي يتم تثبيته

لتثبيت تطبيق خاص بمستخدم النظام، يتم إجراء طلب POST:

curl \
-F "business_app=APP-ID" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/applications"

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

إنشاء رمز وصول

بعد انتهاء مستخدم النظام من تثبيت التطبيق، يمكنه إنشاء رمز وصول دائم. وتنطبق بعض القيود التالية:

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

إليك فيما يلي معلمات استدعاء API:

• business_app: يمثل التطبيق الذي المملوك بواسطة مدير الأعمال الذي ينتمي إليه مستخدم النظام.
• appsecret_proof: يمثل الحقل المحسوب للتطبيق. ويكون هذا الحقل مطلوبًا لضمان قيام الخادم المناسب بإجراء استدعاء واجهة API. ولمزيد من التفاصيل، يمكنك الرجوع إلى أمان تسجيل الدخول.
• scope: يمثل سلسلة مفصولة بفاصلة تحتوي على أذونات موسّعة.
• access_token: رمز ينتمي إلى مسؤول مدير الأعمال أو مستخدم النظام المسؤول أو مستخدم النظام العادي.
• set_token_expires_in_60_days: يمكن تعيينه على true لإنشاء رمز وصول مستخدم النظام منتهي الصلاحية. موصى به. تُعد الرموز التي تنتهي صلاحيتها واحدة من أفضل ممارسات الأمان. يجب على بعض الأنشطة التجارية استخدام الرموز التي تنتهي صلاحيتها. إذا كان هذا المطلب ينطبق على نشاطك التجاري، فسيؤدي حذف هذه المعلمة أو تعيينها على false إلى حدوث خطأ. يجب أن تستخدم كل عمليات الدمج رموزًا تنتهي صلاحيتها لتتوافق مع معايير أمان المنصة المتطورة.

النطاقات المدعومة لمستخدمي النظام:

• ads_management
• ads_read
• attribution_read
• business_management
• catalog_management
• commerce_account_manage_orders
• commerce_account_read_orders
• commerce_account_read_settings
• instagram_basic
• instagram_branded_content_ads_brand
• instagram_branded_content_brand
• instagram_content_publish
• instagram_manage_comments
• instagram_manage_insights
• instagram_manage_messages
• instagram_shopping_tag_products
• leads_retrieval
• page_events
• pages_manage_ads
• pages_manage_cta
• pages_manage_engagement
• pages_manage_instant_articles
• pages_manage_metadata
• pages_manage_posts
• pages_messaging
• pages_read_engagement
• pages_read_user_content
• pages_show_list
• private_computation_access
• publish_video
• read_audience_network_insights
• read_insights
• read_page_mailboxes
• whatsapp_business_management
• whatsapp_business_messaging

إذن تم إيقاف استخدامه، يظهر فقط للتطبيقات التي تم إنشاؤها قبل 24 أبريل 2018

publish_actions

الأذونات المقيدة حسب الإمكانات

لإنشاء appsecret_proof، يمكنك استخدام رمز PHP:

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

في مثال الرمز أعلاه، تشير app_secret_for_the_app_used_in_the_call إلى المفتاح السري للتطبيق الخاص بالتطبيق المُستخدم لإنشاء رمز الوصول. يمكن العثور على المفتاح السري للتطبيق في لوحة معلومات التطبيق.

يجب أن تكون appsecret_proof المجزأة عبارة عن سلسلة مثل "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

لإنشاء رمز وصول دائم لمستخدم النظام، يمكنك إرسال طلب POST:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,pages_read_engagement,pages_show_list" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

لإنشاء رمز وصول تنتهي صلاحيته لمستخدم النظام، يمكنك إرسال طلب POST:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,pages_read_engagement,pages_show_list" \
-F "set_token_expires_in_60_days=true" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

تقوم الاستجابة بإرجاع سلسلة رمز الوصول. وفي حالة عدم تلبية أحد القيود، ستظهر رموز الأخطاء المناسبة. الاستجابة:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

يمكنك أيضًا إنشاء رمز وصول مستخدم النظام باستخدام واجهة المستخدم لمدير الأعمال.

تحديث رمز الوصول

يكون رمز مستخدم النظام الذي تنتهي صلاحيته صالحًا لمدة 60 يومًا من تاريخ الإنشاء أو تاريخ التحديث. للحفاظ على الاستمرارية، يجب على المطوّرين تحديث رمز الوصول خلال 60 يومًا. سيؤدي الفشل في إجراء ذلك إلى خسارة رمز الوصول وسيحتاج المطوّرون إلى الحصول على رمز جديد لاستعادة الوصول إلى API.

لتحديث رمز وصول مستخدم النظام الذي تنتهي صلاحيته، ستحتاج إلى:

• fb_exchange_token: رمز وصول مستخدم نظام صالح
• client_id: معرف التطبيق
• client_secret: المفتاح السري للتطبيق
• set_token_expires_in_60_days: يمكن تعيينه على true لتحديث رمز وصول مستخدم النظام الذي تنتهي صلاحيته.

استعلم عن نقطة النهاية GET oauth/access_token.

عينة من الطلب

curl -i -X GET 
"https://graph.facebook.com/{graph-api-version}/oauth/access_token?  
    grant_type=fb_exchange_token&          
    client_id={app-id}&
    client_secret={app-secret}&
    set_token_expires_in_60_days=true&
    fb_exchange_token={your-access-token}"

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

{
  "access_token":"{expiring-system-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944    // Time left in seconds until the token expires
}

إلغاء رمز الوصول

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

لإلغاء رمز وصول مستخدم النظام، ستحتاج إلى:

• revoke_token: رمز الوصول المراد إلغائه

• client_id: معرف التطبيق

• client_secret: المفتاح السري للتطبيق

• access_token: رمز الوصول لتحديد المستدعي

المتطلبات هي كما يلي:

• يجب أن يتوافق client_id مع التطبيق الفعلي وأن يتأكد من عدم تقييد التطبيق أو تعطيله أو حذفه.

• يجب أن يكون كل مما يأتي متشابهًا، client_id مع التطبيق المثبت لـ revoke_token والتطبيق المثبت لـ access_token وclient_secret.

استعلم عن نقطة النهاية GET oauth/revoke.

عينة من الطلب

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/revoke?   
    client_id={app-id}&
    client_secret={app-secret}&
    revoke_token={system-user-access-token-to-revoke}&
    access_token={your-access-token}"

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

{
  "success":"true",
}

تدوير رمز الوصول

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

1. قم بتحديث رمز وصول مستخدم النظام عبر واجهة API التحديث، والتي ستعمل على إرجاع رمز وصول مستخدم نظام جديد صالح لمدة 60 يومًا من تاريخ التحديث. يظل رمز الوصول القديم يعمل حتى تنتهي صلاحيته (60 يومًا من تاريخ الإنشاء).

2. قم بنشر رمز وصول مستخدم النظام الجديد.

3. قم بإلغاء رمز وصول مستخدم النظام القديم عبر واجهة API الإلغاء. يتم الإبطال على الفور، ولا يمكن استخدام الرمز مرة أخرى بعد الإلغاء.