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

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

هل خدمة App Check مناسبة لي؟

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

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

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

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

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

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

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

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

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

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

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

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

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

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

المتطلبات الأساسية ومتطلبات الأهلية

• تطبيق مثبَّت عليه الإصدار 9.2 أو إصدار أحدث من Places SDK
• معرّف حزمة التطبيق
• معرّف الفريق من Apple Member Center، ضمن "الاشتراك"
• إذا كنت تخطّط لاستخدام 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: إضافة مكتبة App Check وإعدادها

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

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

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

     Places Swift SDK لأجهزة 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:

     Places Swift SDK لأجهزة 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: تهيئة واجهتَي Places API وApp Check API

1. في ملف AppDelegate، ابدأ Places API على النحو التالي:

   Places Swift SDK لأجهزة iOS

   PlacesClient.provideAPIKey("YOUR_API_KEY")

   Swift

   GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

   Objective-C

   [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];

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

   Places Swift SDK لأجهزة iOS

   PlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

   Swift

   GMSPlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

   Objective-C

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

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

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

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

• إنشاء مصنع موفّر تصحيح الأخطاء في App Check وتعيينه

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

  Places Swift SDK لأجهزة 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.
• لمزيد من المعلومات والتعليمات، يُرجى الاطّلاع على مستندات App Check.

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

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

• إنشاء مصنع موفّر تصحيح الأخطاء في App Check وتعيينه

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

  Places Swift SDK لأجهزة 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)

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

الخطوة 6: مراقبة طلبات تطبيقك وتحديد إجراء التنفيذ

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

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