بدء استخدام مجموعة Facebook SDK لنظام Android

تتناول هذه الوثائق كيفية بدء دمج تطبيق Android مع فيسبوك باستخدام مجموعة Facebook SDK لنظام Android. الإصدار الحالي لمجموعة Facebook SDK لنظام Android هو 12.0.0 ويتطلب Android API بالإصدار 15. لمزيد من المعلومات حول الإصدارات والميزات، راجع مجموعة Facebook SDK لنظام Android.

عند استخدام مجموعة Facebook SDK، يتم تسجيل بعض الأحداث في تطبيقك وتجميعها تلقائيًا ما لم تقم بتعطيل التسجيل التلقائي للأحداث. للحصول على المزيد من التفاصيل حول المعلومات التي يتم تجميعها وكيفية تعطيل التسجيل التلقائي للأحداث، يمكنك الرجوع إلى التسجيل التلقائي لأحداث التطبيق.

يمكنك إعداد تطبيقك لاستخدام مجموعة Facebook SDK لنظام Android بالطرق التالية:

من خلال استخدام دليل البدء السريع.
عن طريق إعداد مشروعك من خلال مجموعة Facebook SDK لنظام Android.

البدء السريع

للحصول على معرف تطبيق فيسبوك، يمكنك تكوين إعدادات التطبيق واستيراد مجموعة Facebook SDK لنظام Android، ثم انقر على الزر أدناه واتبع التعليمات.

دليل البدء السريع في نظام Android

قبل البدء

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

التعرف على إذن معرف الإعلان

بدءًا من الإصدار 13.0.0، سيعمل كل تطبيق تقوم بإنشائه باستخدام مجموعة Facebook SDK لنظام Android تلقائيًا على إضافة إذن معرف الإعلان إلى تطبيقك. لمزيد من المعلومات، راجع معرف الإعلان - مساعدة Play Console.

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

إعداد Android Studio

إنشاء المشروع

لاستخدام مجموعة Facebook SDK في مشروع Android Studio، أضف مجموعة SDK كتبعية إنشاء وقم باستيراد مجموعة SDK.

انتقل إلى Android Studio | مشروع جديد | الحد الأدنى لإصدار مجموعة SDK.
حدّد API 15: نظام Android بالإصدار 4.0.3 (IceCreamSandwich) أو أحدث وأنشئ مشروعًا جديدًا.
افتح الملف Gradle Scripts | build.gradle (Project: <your_project>) وأضف ما يلي:
```
mavenCentral()
```
احفظ الملف build.gradle (Project: <your_project>) وأغلقه.
افتح الملف Gradle Scripts | build.gradle (Module: app) وأضف ما يلي إلى القسم dependencies:
```
implementation 'com.facebook.android:facebook-android-sdk:latest.release'
```
احفظ الملف build.gradle (Module: app) وأغلقه.
أنشئ مشروعك. الآن يمكنك استيراد com.facebook.FacebookSdk في تطبيقك.

تحديث ملف البيانات

أضف معرف التطبيق ورمز البرنامج إلى ملف السلسلة بمشروعك وقم بتحديث ملف البيانات. قم بما يلي:

افتح الملف /app/res/values/strings.xml في مشروع التطبيق.
أضف عناصر string مع الأسماء facebook_app_id وfacebook_client_token وقم بتعيين القيم في معرف التطبيق ورمز البرنامج. على سبيل المثال، إذا كان معرف تطبيقك 1234 ورمز البرنامج 56789، فسيبدو الرمز كما يلي:
```
<string name="facebook_app_id">1234</string><string name="facebook_client_token">56789</string>
```
افتح الملف /app/manifests/AndroidManifest.xml في مشروع التطبيق.

أضف عناصر meta-data إلى العنصر application لمعرف تطبيقك ورمز البرنامج:

<application android:label="&#064;string/app_name" ...>
    ...
    <meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/><meta-data android:name="com.facebook.sdk.ClientToken" android:value="@string/facebook_client_token"/>
    ...
</application>

أضف عنصر uses-permission إلى ملف البيانات الموجود بعد عنصر application:
```
<uses-permission android:name="android.permission.INTERNET"/>
```
(اختياري) لإلغاء الاشتراك من إذن معرف الإعلان، أضف عنصر uses-permission إلى ملف البيانات الموجود بعد العنصر application:
```
<uses-permission android:name="com.google.android.gms.permission.AD_ID" tools:node="remove"/>
```
أنشئ مشروعك.

تمكين المشاركة

إذا كنت تشارك روابط أو صور أو فيديو من تطبيقك، فوضح صلاحية FacebookContentProvider في ملف البيانات. قم بما يلي:

افتح الملف /app/manifests/AndroidManifest.xml في مشروع التطبيق.
أضف عنصر provider إلى ملف البيانات المرتبط بصلاحية FacebookContentProvider. ألحق معرف التطبيق بنهاية القيمة authorities. على سبيل المثال، إذا كان معرف التطبيق 1234، فسيكون إعلان الرابط كما يلي:
```
<provider android:authorities="com.facebook.app.FacebookContentProvider1234"
    android:name="com.facebook.FacebookContentProvider"
    android:exported="true" />
```
أنشئ مشروعك.

تشغيل عينات من التطبيقات

ترتبط العينات التالية بمجموعة Facebook SDK لنظام Android:

HelloFacebookSample — يوضح إمكانية الوصول إلى الملف الشخصي وتحديثات الحالة وتحميل الصور.

يمكنك تجربة العينات من خلال استيراد مجموعة Facebook SDK إلى مشروع Android Studio. تحتوي العينات على تبعية المشروع بدلاً من تبعية المستودع المركزي عبر maven central أو jcenter. هذا بحيث عندما تحصل نسخة محلية من مجموعة SDK على تحديثات، يمكن للعينات أن تعكس التغييرات.

لتشغيل عينات التطبيقات بشكل سريع، يمكنك إنشاء تجزئات المفاتيح لبيئات التطوير لديك. وأضف هذه العلامات إلى الملف الشخصي لمطوّر فيسبوك المخصص لعينات التطبيقات. يتم تضمين أداة المفاتيح المستخدمة في إنشاء تجزئات المفاتيح، مع Java SE Development Kit (JDK) التي قمت بتثبيتها كجزء من إعداد بيئة التطوير لديك. يتوفر OpenSSL للتنزيل من OpenSSL.

في نظام OS X، قم بتشغيل:

keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64

في نظام Windows، تحتاج إلى ما يلي:

أداة إدارة المفتاح والشهادة (keytool) من مجموعة التطوير Java Development Kit
OpenSSL لمكتبة Windows من أرشيف Google Code

قم بتشغيل الأمر التالي في موجه الأوامر ضمن مجلد مجموعة Java SDK. ويؤدي هذا إلى إنشاء سلسلة مكونة من 28 حرفًا.

keytool -exportcert -alias androiddebugkey -keystore %HOMEPATH%\.android\debug.keystore | openssl sha1 -binary | openssl
base64

انتقل إلى موقع مطوّر فيسبوك. سجّل الدخول إلى فيسبوك، وانتقل إلى إعدادات المطوّر باستخدام القائمة المنسدلة في أعلى اليسار:

في إعدادات المطوّر، حدّد عينة من التطبيق من القائمة وأضف تجزئة المفتاح في الملف الشخصي واحفظها:

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

يمكنك الآن تجميع كل العينات وتشغيلها - بما في ذلك تلك التي تستخدم تسجيل دخول فيسبوك.

إنشاء تجزئة مفتاح التطوير

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

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

في نظام OS X أو نظام Windows، يمكنك الحصول على تجزئة مفتاح عن طريق إنشائها أو باستخدام القيمة التي يتم إرجاعها بواسطة Settings.getApplicationSignature(Context). للحصول على إرشادات، راجع تشغيل عينات التطبيقات .

إنشاء تجزئة مفتاح الإصدار

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

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

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

لإنشاء تجزئة مفتاح الإصدار، شغّل الأمر التالي في نظام Mac أو Windows مع استبدال الاسم المستعار لمفتاح الإصدار والمسار بمخزن المفاتيح لديك.

في نظام Mac OS، قم بتشغيل:

keytool -exportcert -alias <RELEASE_KEY_ALIAS> -keystore <RELEASE_KEY_PATH> | openssl sha1 -binary | openssl base64

في نظام Windows، تحتاج إلى ما يلي:

أداة إدارة المفتاح والشهادة (keytool) من مجموعة التطوير Java Development Kit
OpenSSL لمكتبة Windows من أرشيف Google Code

قم بتشغيل الأمر التالي في موجه الأوامر ضمن مجلد مجموعة Java SDK:

keytool -exportcert -alias <RELEASE_KEY_ALIAS> -keystore <RELEASE_KEY_PATH> | PATH_TO_OPENSSL_LIBRARY\bin\openssl sha1 -binary | PATH_TO_OPENSSL_LIBRARY\bin\openssl base64

تأكد من استخدام كلمة السر التي قمت بتعيينها عند إنشاء مفتاح الإصدار لأول مرة.

يجب أن ينشئ هذا الأمر سلسلة مكونة من 28 حرفًا. انسخ تجزئة مفتاح الإصدار هذه والصقها في إعدادات Android لمعرف تطبيق فيسبوك.

يجب أيضًا التحقق من أن إعداد نظام Android لمعرف تطبيق فيسبوك يحتوي كذلك على اسم الحزمة الصحيح وفئة النشاط الرئيسية لحزمة نظام Android.

استخدام مجموعة Facebook SDK لنظام Android من خلال Maven

يمكنك إعلان تبعية Maven من خلال أحدث إصدار متوفر من مجموعة Facebook SDK لنظام Android.

<dependency>
  <groupId>com.facebook.android</groupId>
  <artifactId>facebook-android-sdk</artifactId>
  <version>PUT_LATEST_VERSION_HERE</version>
</dependency>

استكشاف أخطاء عينات التطبيقات وإصلاحها

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

يظهر مربع حوار "تسجيل الدخول" أصلي ولكن بعد قبول الأذونات تظل في حالة تسجيل خروج. تحتوي أداة logcat أيضًا على استثناء:

12-20 10:23:24.507: W/fb4a:fb:OrcaServiceQueue(504):
com.facebook.orca.protocol.base.ApiException: remote_app_id does not match stored id

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

تحقق من تجزئة المفتاح ويمكنك التأكد من استخدام تجزئة المفتاح الصحيحة. I

يمكنك أيضًا تعديل عينة الرمز يدويًا لاستخدام تجزئة المفتاح الصحيحة. على سبيل المثال في الفئة HelloFacebookSampleActivity قم بإجراء تغيير مؤقت على onCreate():

@Override
public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    
    // Add code to print out the key hash
    try {
        PackageInfo info = getPackageManager().getPackageInfo(
                "com.facebook.samples.hellofacebook", 
                PackageManager.GET_SIGNATURES);
        for (Signature signature : info.signatures) {
            MessageDigest md = MessageDigest.getInstance("SHA");
            md.update(signature.toByteArray());
            Log.d("KeyHash:", Base64.encodeToString(md.digest(), Base64.DEFAULT));
            }
    } catch (NameNotFoundException e) {
        
    } catch (NoSuchAlgorithmException e) {
        
    }
    
    ...

احفظ التغييرات وأعد تشغيل عينة الرمز. تحقق من إخراج أداة logcat بحثًا عن رسالة مشابهة لهذه:

12-20 10:47:37.747: D/KeyHash:(936): 478uEnKQV+fMQT8Dy4AKvHkYibo=

احفظ تجزئة المفتاح في الملف الشخصي للمطوّر. أعد تشغيل عينات الرمز وتحقق من أنه يمكنك تسجيل الدخول بنجاح.

راجع أيضًا

تصغير حجم التطبيق وحجبه وتحسينه