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

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

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

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

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

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

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

في ما يلي الخطوات التي يجب اتّباعها بشكل عام لدمج تطبيقك مع App Check:

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

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

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

نقاط يجب وضعها في الاعتبار عند التخطيط لدمج أداة "فحص التطبيق"

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

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

يحدّد المدّة التي يكون فيها رمز 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:
- تعليمات شهادة إثبات الملكية للتطبيقات
- تعليمات التحقّق من الجهاز
شغِّل App Check.
- إذا كنت تستخدم ميزة "إثبات صحة التطبيق"، اتّبِع مستندات مطوّري Firebase حول ميزة "إثبات صحة التطبيق".
  اتّبِع تعليمات Firebase App Check لإنشاء عملية تنفيذ لـ 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 للحصول على مزيد من المعلومات والتعليمات.