تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

استخدام App Check لتأمين مفتاح واجهة برمجة التطبيقات

توفّر ميزة فحص التطبيقات من Firebase حماية للطلبات الواردة من تطبيقك إلى Google Maps Platform من خلال حظر الزيارات الواردة من مصادر غير التطبيقات المشروعة. ويتم ذلك من خلال البحث عن رمز مميّز من موفّر إثبات الهوية، مثل App Attest. يساعد دمج تطبيقاتك مع أداة "فحص التطبيقات" في الحماية من الطلبات الضارّة، وبالتالي لا يتم تحصيل رسوم منك مقابل طلبات البيانات غير المصرّح بها من واجهة برمجة التطبيقات.

هل أداة "فحص التطبيقات" مناسبة لي؟

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

إذا كنت تستخدم حزمة تطوير البرامج (SDK) الأصلية لتطبيق "الأماكن" لا تتوفّر أداة "فحص التطبيق" إلا لحزمة Places SDK (الإصدار الجديد).
التطبيقات الخاصة أو التجريبية إذا لم يكن تطبيقك متاحًا للجميع، لن يكون تطبيق "فحص التطبيق" ضروريًا.
إذا كان تطبيقك يُستخدَم فقط من خادم إلى آخر، لن يكون تطبيق "فحص التطبيقات" مطلوبًا. ومع ذلك، إذا كان الخادم الذي يتواصل مع GMP يستخدمه عملاء متاحون للجميع (مثل التطبيقات المتوافقة مع الأجهزة الجوّالة)، ننصحك باستخدام App Check لحماية هذا الخادم بدلاً من GMP.
لن تعمل مقدّمو بيانات الاعتماد المقترَحون من App Check على الأجهزة التي يراها مقدّمو بيانات الاعتماد مُخترَقة أو غير موثوق بها. إذا كنت بحاجة إلى إتاحة هذه الأجهزة، يمكنك نشر خدمة إثبات الهوية المخصّصة. لمزيد من المعلومات، يُرجى الاطّلاع على التعليمات.

نظرة عامة على خطوات التنفيذ

في ما يلي الخطوات التي يجب اتّباعها بشكل عام لدمج تطبيقك مع أداة "فحص التطبيقات":

أضِف Firebase إلى تطبيقك.
أضِف مكتبة App Check وأبدِئها.
أضِف مقدّم الرمز المميّز إلى تطبيقك.
شغِّل واجهتَي برمجة التطبيقات Places API وApp Check API.
فعِّل ميزة تصحيح الأخطاء.
يمكنك مراقبة طلبات تطبيقك واتخاذ قرار بشأن تنفيذها.

بعد الدمج مع App Check، ستتمكّن من الاطّلاع على مقاييس عدد الزيارات إلى الخلفية في وحدة تحكّم Firebase. تقدّم هذه المقاييس تفاصيل عن الطلبات حسب ما إذا كانت مصحوبة برمز مميّز صالح لتطبيق "فحص التطبيق". اطّلِع على مستندات فحص التطبيقات من Firebase للحصول على مزيد من المعلومات.

عندما تكون متأكدًا من أنّ معظم الطلبات واردة من مصادر مشروعة وأنّ المستخدمين قد ثبَّتوا أحدث إصدار من تطبيقك يتضمّن تنفيذ ميزة "فحص التطبيق"، يمكنك تفعيل ميزة فرض التطبيق. بعد تفعيل ميزة "فرض التطبيق"، سترفض ميزة "فحص التطبيق" جميع الزيارات التي لا تتضمّن رمز أمان صالحًا.

اعتبارات عند التخطيط لدمج App Check

في ما يلي بعض الأمور التي يجب مراعاتها عند التخطيط لعملية الدمج:

إنّ مقدّمي خدمات إثبات الهوية الذين ننصح بهم، Device Check أو App Attest، يخضعون للقيود والحصص التي تحدّدها Apple.
يمكنك اختيار استخدام مقدّم شهادة اعتماد مخصّص، على الرغم من أنّ هذه حالة استخدام متقدّمة. اطّلِع على مستندات فحص التطبيقات من Firebase للحصول على مزيد من المعلومات.
سيواجه مستخدمو تطبيقك بعض التأخير في بدء التشغيل. بعد ذلك، ستتم أي عملية إعادة إثبات ملكية دورية في الخلفية، ومن المفترض ألا يواجه المستخدمون أي وقت استجابة بعد ذلك. يعتمد مقدار وقت الاستجابة الدقيق عند بدء التشغيل على مقدّم شهادة الاعتماد الذي تختاره.

تحدد المدة التي يكون فيها رمز App Check صالحًا (مدة البقاء) وتيرة عمليات إعادة تقديم بيانات الاعتماد. يمكن ضبط هذه المدة في وحدة تحكّم Firebase. تحدث إعادة تقديم الشهادة عند مرور نصف فترة صلاحية ذاكرة التخزين المؤقت تقريبًا. لمزيد من المعلومات، اطّلِع على مستندات Firebase لمزوّد بيانات الإثبات.

دمج تطبيقك مع App Check

المتطلّبات الأساسية

تطبيق تم تثبيت الإصدار 9.2 أو إصدار أحدث من حزمة تطوير البرامج (SDK) لتطبيق "الأماكن" عليه
معرّف حزمة التطبيق
رقم تعريف فريقك من Apple Member Center (مركز الأعضاء في Apple) ضمن "الاشتراك"
إذا كنت تخطّط لاستخدام ميزة "التحقّق من الجهاز"، عليك الحصول على ملف المفتاح الخاص ومعرّف المفتاح.
يجب أن تكون مالك التطبيق في Cloud Console.
ستحتاج إلى رقم تعريف مشروع التطبيق من Cloud Console.

الخطوة 1: إضافة Firebase إلى تطبيقك

اتّبِع التعليمات الواردة في مستندات مطوّري Firebase لإضافة Firebase إلى تطبيقك.

عند تسجيل تطبيقك، ستحصل على ملف الإعدادات GoogleService-Info.plist. أضِف هذا الملف غير المعدَّل إلى مستوى الجذر في تطبيقك.

ملاحظة: في الخطوة 5 من مستندات مطوّري Firebase، حيث تضيف وحدات Firebase إلى ملف AppDelegate، أضِف الوحدات التالية:

Swift

import FirebaseCore
import FirebaseAppCheck
import GooglePlaces

Objective-C

@import FirebaseCore;      
@import FirebaseAppCheck;
@import GooglePlaces;

الخطوة 2: إضافة مكتبة App Check وبدء تشغيل App Check

يوفّر Firebase تعليمات لكل مقدّم إثبات هوية تلقائي. توضّح لك هذه التعليمات كيفية إعداد مشروع على Firebase وإضافة مكتبة App Check إلى تطبيقك. اتّبِع نماذج الرموز البرمجية المقدّمة لإعداد App Check.

اتّبِع تعليمات Firebase لإضافة مكتبة App Check:
- تعليمات شهادة إثبات الملكية للتطبيقات
- تعليمات التحقّق من الجهاز
شغِّل ميزة "فحص التطبيق".
- إذا كنت تستخدِم ميزة "إثبات صحة التطبيق"، اتّبِع مستندات مطوّري Firebase حول ميزة "إثبات صحة التطبيق".
  اتّبِع تعليمات فحص التطبيقات من Firebase لإنشاء عملية تنفيذ لـ AppCheckProviderFactory وإضافتها إلى ملف AppDelegate.
  Swift
  let providerFactory = YourAppCheckProviderFactory() AppCheck.setAppCheckProviderFactory(providerFactory)
  Objective-C
  YourAppCheckProviderFactory *providerFactory = [[YourAppCheckProviderFactory alloc] init]; [FIRAppCheck setAppCheckProviderFactory:providerFactory];
- إذا كنت تستخدم ميزة "فحص الجهاز"، أضِف ما يلي إلى AppDelegate:
  Swift
  AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())
  Objective-C
  [FIRAppCheck setAppCheckProviderFactory:providerFactory];

الخطوة 3: إضافة موفِّر الرموز المميّزة

أنشئ ملفًا باسم AppCheckTokenProvider (أو إذا كنت تستخدم Objective-C، أنشئ ملفين باسم AppCheckTokenProvider.h وAppCheckTokenProvider.m) على مستوى جذر تطبيقك. أضِف عبارات الاستيراد وتعريف الفئة التاليَين:

Swift

// AppCheckTokenProvider.swift

import FirebaseAppCheck
import Foundation
import GooglePlaces

class AppCheckTokenProvider: NSObject, GMSPlacesAppCheckTokenProvider {
  func fetchAppCheckToken() async throws -> String {
    return try await AppCheck.appCheck().token(forcingRefresh: false).token
  }
}

Objective-C

// AppCheckTokenProvider.h

@import Foundation;
@import GooglePlaces;

@interface AppCheckTokenProvider : NSObject <GMSPlacesAppCheckTokenProvider>
@end

// AppCheckTokenProvider.m

#import "AppCheckTokenProvider.h"

@import FirebaseAppCheck;

@implementation AppCheckTokenProvider

- (void)fetchAppCheckTokenWithCompletion:(nonnull GMSAppCheckTokenCompletion)completion {
  [[FIRAppCheck appCheck]
      tokenForcingRefresh:NO
               completion:^(FIRAppCheckToken *_Nullable token, NSError *_Nullable error) {
                 if (token) {
                   completion(token.token, nil);
                 } else {
                   completion(nil, error);
                 }
               }];
}

@end

الخطوة 4: إعداد واجهات برمجة التطبيقات Places وApp Check

في ملف AppDelegate، يمكنك إعداد Places API:

Swift

GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

Objective-C

[GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

بعد ذلك، يمكنك إعداد واجهة برمجة التطبيقات App Check API:

Swift

GMSPlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

Objective-C

[GMSPlacesClient setAppCheckTokenProvider:[[AppCheckTokenProvider alloc] init]];

الخطوة 5: تفعيل تصحيح الأخطاء (اختياري)

إذا أردت تطوير تطبيقك واختباره على جهازك، أو تشغيله في بيئة دمج مستمر (CI)، يمكنك إنشاء إصدار لتصحيح أخطاء تطبيقك يستخدم مفتاح سر لتصحيح الأخطاء من أجل الحصول على رموز مميّزة صالحة لفحص التطبيق. يتيح لك ذلك تجنُّب استخدام مقدّمي بيانات اعتماد حقيقيين في إصدار تصحيح الأخطاء.

لاختبار تطبيقك في المحاكي أو على جهاز اختباري:

أنشئ مصنع مقدّم تصحيح الأخطاء في App Check واضبطه.

يعالج نموذج الرمز البرمجي هذا كلاً من سيناريوهات تصحيح الأخطاء والإصدار العلني:

Swift

#if targetEnvironment(simulator)
      let providerFactory = AppCheckDebugProviderFactory()
#else
      let providerFactory = YourAppCheckProviderFactory()
#endif

Objective-C

if (targetEnvironment == simulator){

FIRAppCheckDebugProviderFactory *providerFactory =
      [[FIRAppCheckDebugProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
}

else {

YourAppCheckProviderFactory *providerFactory =
      [[YourAppCheckProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
}

فعِّل التسجيل في مشروع Xcode، واطلق التطبيق، وابحث عن رمز التفعيل المحلي لتصحيح الأخطاء في السجلّ.
أضِف هذا الرمز المميّز إلى وحدة تحكّم Firebase.
لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات App Check.

لتشغيل تطبيقك في بيئة تطوير متكامل (CI)، اتّبِع الخطوات التالية:

أنشئ رمزًا مميّزًا لتصحيح الأخطاء في وحدة تحكّم Firebase وأضِفه إلى متجر المفاتيح الآمن في نظام التطوير المتكامل (CI).
في Xcode، أضِف متغيّر بيئة إلى مخطّط الاختبار باستخدام الاسم FIRAAppCheckDebugToken و$(APP_CHECK_DEBUG_TOKEN) (أو ما شابه) كقيمة.
في النص البرمجي لاختبار التكامل المستمر، مرِّر رمز تصحيح الأخطاء كبيئة.

أنشئ مصنع مقدّم تصحيح الأخطاء في App Check واضبطه.

يعالج نموذج الرمز البرمجي هذا كلاً من سيناريوهات تصحيح الأخطاء والإصدار العلني:

Swift

  #if targetEnvironment(ci)
        let providerFactory = AppCheckDebugProviderFactory()
        AppCheck.setAppCheckProviderFactory(providerFactory)
  #else
        let providerFactory = YourAppCheckProviderFactory()
  #endif

Objective-C

if (targetEnvironment == ci) {
FIRAppCheckDebugProviderFactory *providerFactory =
      [[FIRAppCheckDebugProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
}

else {
YourAppCheckProviderFactory *providerFactory =
      [[YourAppCheckProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
}

لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات App Check.

الخطوة 6: مراقبة طلبات تطبيقك واتخاذ قرار بشأن تنفيذها

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

يمكنك الاطّلاع على مستندات فحص التطبيقات من Firebase للحصول على مزيد من المعلومات والتعليمات.