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

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

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

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

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

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

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

1. أضِف Firebase إلى تطبيقك.
2. أضِف مكتبة "فحص التطبيقات" وأعِدّها.
3. أضِف مقدّم الرموز المميّزة إلى تطبيقك.
4. أعِدّ واجهات برمجة التطبيقات "الأماكن" و"فحص التطبيقات".
5. فعِّل تصحيح الأخطاء.
6. راقِب طلبات تطبيقك وحدِّد ما إذا كنت تريد فرض ميزة "فحص التطبيقات".

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

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

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

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

• يخضع مقدّما خدمات المصادقة اللذان ننصح بهما، وهما Device Check أو App Attest، للحصص والقيود التي تفرضها Apple.

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

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

  تحدّد المدة التي يكون فيها الرمز المميّز من ميزة "فحص التطبيقات" صالحًا (مدة البقاء أو TTL) عدد مرات إعادة المصادقة. يمكن ضبط هذه المدة في وحدة تحكُّم Firebase. تحدث عملية إعادة المصادقة عندما ينقضي نصف مدة البقاء تقريبًا. لمزيد من المعلومات، يُرجى الاطّلاع على مستندات Firebase الخاصة بمقدّم خدمة المصادقة.

دمج تطبيقك مع ميزة "فحص التطبيقات"

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

• تطبيق مثبَّت عليه الإصدار 9.2 أو إصدار أحدث من حزمة تطوير برامج الأماكن
• معرّف حزمة التطبيق .
• معرّف فريقك من مركز مطوّري Apple، ضمن "الاشتراك"
• إذا كنت تخطط لاستخدام Device Check، يجب توفير ملف المفتاح الخاص ومعرّف المفتاح.
• يجب أن تكون مالك التطبيق في Cloud Console.
• ستحتاج إلى رقم تعريف مشروع التطبيق من Cloud Console

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

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

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

import FirebaseCore
import FirebaseAppCheck
import GooglePlacesSwift

import FirebaseCore
import FirebaseAppCheck
import GooglePlaces

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

الخطوة 2: إضافة مكتبة "فحص التطبيقات" وإعداد ميزة "فحص التطبيقات"

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

1. اتّبِع تعليمات Firebase لإضافة مكتبة "فحص التطبيقات":
   • تعليمات App Attest.
   • تعليمات Device Check
2. أعِدّ ميزة "فحص التطبيقات".
   • إذا كنت تستخدم App Attest، اتّبِع مستندات مطوّري Firebase الخاصة بـ App Attest..

     اتّبِع تعليمات ميزة "فحص التطبيقات من Firebase" لإنشاء عملية تنفيذ AppCheckProviderFactory وإضافتها إلى ملف AppDelegate.

     حزمة تطوير برامج الأماكن من Google لأجهزة iOS

     let providerFactory = YourAppCheckProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)

     Swift

     let providerFactory = YourAppCheckProviderFactory()
     AppCheck.setAppCheckProviderFactory(providerFactory)

     Objective-C

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

   • إذا كنت تستخدم Device Check، أضِف ما يلي إلى ملف AppDelegate:

     حزمة تطوير برامج الأماكن من Google لأجهزة iOS

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Swift

     AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

     Objective-C

     [FIRAppCheck setAppCheckProviderFactory:providerFactory];
           

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

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

// AppCheckTokenProvider.swift

import FirebaseAppCheck
import Foundation
import GooglePlacesSwift
      
struct TokenProvider: AppCheckTokenProvider {
  func fetchAppCheckToken() async throws -> String {
    return try await AppCheck.appCheck().token(forcingRefresh: false).token
  }
}
      

// 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
  }
}

// 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: إعداد واجهات برمجة التطبيقات "الأماكن" و"فحص التطبيقات"

1. في ملف AppDelegate، أعِدّ واجهة برمجة التطبيقات "الأماكن":

   حزمة تطوير برامج الأماكن من Google لأجهزة iOS

   PlacesClient.provideAPIKey("YOUR_API_KEY")

   Swift

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

   Objective-C

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

2. بعد ذلك، أعِدّ واجهة برمجة التطبيقات "فحص التطبيقات":

   حزمة تطوير برامج الأماكن من Google لأجهزة iOS

   PlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

   Swift

   GMSPlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

   Objective-C

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

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

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

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

• أنشئ وأعِدّ مصنع مقدّم خدمة تصحيح الأخطاء لميزة "فحص التطبيقات".

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

  حزمة تطوير برامج الأماكن من Google لأجهزة iOS

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

  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.
• لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات ميزة "فحص التطبيقات".

لتشغيل تطبيقك في بيئة تكامل مستمر:

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

• أنشئ وأعِدّ مصنع مقدّم خدمة تصحيح الأخطاء لميزة "فحص التطبيقات".

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

  حزمة تطوير برامج الأماكن من Google لأجهزة iOS

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

  Swift

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

  Objective-C

  #if DEBUG
  id<FIRAppCheckProviderFactory> providerFactory =
      [[FIRAppCheckDebugProviderFactory alloc] init];
  #else  // DEBUG
  id<FIRAppCheckProviderFactory> providerFactory =
      [[YourAppCheckProviderFactory alloc] init];
  #endif  // DEBUG
  AppCheck.setAppCheckProviderFactory(providerFactory)

• لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات ميزة "فحص التطبيقات".

الخطوة 6: مراقبة طلبات تطبيقك وتحديد ما إذا كنت تريد فرض ميزة "فحص التطبيقات"

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

لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات ميزة "فحص التطبيقات من Firebase".