پلتفرم مورد نظر را انتخاب کنید: اندروید، iOS، جاوا اسکریپت

برای ایمن‌سازی کلید API خود از App Check استفاده کنید

Firebase App Check با مسدود کردن ترافیکی که از منابعی غیر از برنامه‌های قانونی می‌آید، از تماس‌های برنامه شما به پلتفرم Google Maps محافظت می‌کند. این کار را با بررسی وجود توکن از یک ارائه‌دهنده گواهی مانند App Attest انجام می‌دهد. ادغام برنامه‌های شما با App Check به محافظت در برابر درخواست‌های مخرب کمک می‌کند، بنابراین برای تماس‌های API غیرمجاز هزینه‌ای از شما دریافت نمی‌شود.

آیا اپ چک برای من مناسب است؟

در بیشتر موارد، App Check توصیه می‌شود، با این حال در موارد زیر نیازی به آن نیست یا پشتیبانی نمی‌شود:

  • شما از SDK اصلی Places استفاده می‌کنید. App Check فقط برای Places SDK (جدید) پشتیبانی می‌شود .
  • برنامه‌های خصوصی یا آزمایشی. اگر برنامه شما به صورت عمومی قابل دسترسی نیست، نیازی به بررسی برنامه نیست.
  • اگر برنامه شما فقط به صورت سرور به سرور استفاده می‌شود، نیازی به App Check نیست. با این حال، اگر سروری که با GMP ارتباط برقرار می‌کند توسط کلاینت‌های عمومی (مانند برنامه‌های تلفن همراه) استفاده می‌شود، استفاده از App Check را برای محافظت از آن سرور به جای GMP در نظر بگیرید.
  • ارائه‌دهندگان گواهی توصیه‌شده توسط App Check روی دستگاه‌هایی که توسط ارائه‌دهنده گواهی شما در معرض خطر یا غیرقابل اعتماد تشخیص داده می‌شوند، کار نخواهند کرد. اگر نیاز به پشتیبانی از چنین دستگاه‌هایی دارید، می‌توانید یک سرویس گواهی سفارشی راه‌اندازی کنید. برای اطلاعات بیشتر، به دستورالعمل‌ها مراجعه کنید.

مرور کلی مراحل اجرا

در سطح بالا، این مراحلی است که برای ادغام برنامه خود با App Check دنبال خواهید کرد:

  1. فایربیس را به برنامه خود اضافه کنید.
  2. کتابخانه App Check را اضافه و مقداردهی اولیه کنید.
  3. ارائه دهنده توکن را به برنامه خود اضافه کنید.
  4. APIهای Places و App Check را مقداردهی اولیه کنید.
  5. اشکال‌زدایی را فعال کنید.
  6. درخواست‌های برنامه خود را رصد کنید و در مورد اجرای آنها تصمیم بگیرید.

پس از ادغام با App Check، می‌توانید معیارهای ترافیک backend را در کنسول Firebase مشاهده کنید. این معیارها، درخواست‌ها را بر اساس اینکه آیا با یک توکن معتبر App Check همراه هستند یا خیر، تفکیک می‌کنند. برای اطلاعات بیشتر به مستندات Firebase App Check مراجعه کنید.

وقتی مطمئن شدید که بیشتر درخواست‌ها از منابع قانونی هستند و کاربران به آخرین نسخه برنامه شما که شامل پیاده‌سازی App Check شما می‌شود، به‌روزرسانی شده‌اند، می‌توانید اجرای قانون را فعال کنید. پس از فعال شدن اجرای قانون، App Check تمام ترافیک بدون توکن معتبر App Check را رد می‌کند.

ملاحظات هنگام برنامه‌ریزی ادغام App Check

در اینجا مواردی وجود دارد که باید هنگام برنامه‌ریزی برای ادغام خود در نظر بگیرید:

  • ارائه‌دهندگان گواهی که ما توصیه می‌کنیم، یعنی Device Check یا App Attest ، مشمول سهمیه‌ها و محدودیت‌های تعیین‌شده توسط اپل هستند.

    شما می‌توانید از یک ارائه‌دهنده گواهی سفارشی استفاده کنید، اگرچه این یک مورد استفاده پیشرفته است. برای اطلاعات بیشتر به مستندات Firebase App Check مراجعه کنید.

  • کاربران برنامه شما در هنگام راه‌اندازی با کمی تأخیر مواجه خواهند شد. با این حال، پس از آن، هرگونه تأیید مجدد دوره‌ای در پس‌زمینه رخ خواهد داد و کاربران دیگر نباید هیچ تأخیری را تجربه کنند. میزان دقیق تأخیر در هنگام راه‌اندازی به ارائه‌دهنده تأییدیه‌ای که انتخاب می‌کنید بستگی دارد.

    مدت زمانی که توکن App Check معتبر است ( زمان حیات یا TTL) تعداد دفعات تأیید مجدد را تعیین می‌کند. این مدت زمان را می‌توان در کنسول Firebase پیکربندی کرد. تأیید مجدد زمانی اتفاق می‌افتد که تقریباً نیمی از TTL سپری شده باشد. برای اطلاعات بیشتر، به اسناد Firebase مربوط به ارائه‌دهنده تأیید خود مراجعه کنید.

برنامه خود را با App Check ادغام کنید

پیش‌نیازها و الزامات

  • برنامه‌ای که نسخه ۹.۲ یا بالاتر Places SDK روی آن نصب شده باشد.
  • شناسه بسته برنامه .
  • شناسه تیم شما از مرکز اعضای اپل، در بخش عضویت.
  • اگر قصد دارید از Device Check استفاده کنید، فایل کلید خصوصی و شناسه کلید شما.
  • شما باید مالک برنامه در Cloud Console باشید.
  • شما به شناسه پروژه برنامه از Cloud Console نیاز خواهید داشت.

مرحله ۱: اضافه کردن فایربیس به برنامه

برای افزودن Firebase به برنامه خود ، دستورالعمل‌های موجود در مستندات توسعه‌دهندگان Firebase را دنبال کنید.

وقتی برنامه خود را ثبت می‌کنید، یک فایل پیکربندی به نام GoogleService-Info.plist دریافت خواهید کرد. این فایل را بدون تغییر، به سطح ریشه برنامه خود اضافه کنید.

مکان‌های Swift SDK برای iOS 

import FirebaseCore
import FirebaseAppCheck
import GooglePlacesSwift

سویفت 

import FirebaseCore
import FirebaseAppCheck
import GooglePlaces

هدف-سی 

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

مرحله ۲: کتابخانه App Check را اضافه کنید و App Check را مقداردهی اولیه کنید

فایربیس برای هر ارائه‌دهنده‌ی گواهی پیش‌فرض، دستورالعمل‌هایی ارائه می‌دهد. این دستورالعمل‌ها به شما نشان می‌دهند که چگونه یک پروژه‌ی فایربیس راه‌اندازی کنید و کتابخانه‌ی App Check را به برنامه‌ی خود اضافه کنید. برای راه‌اندازی اولیه‌ی App Check، نمونه‌های کد ارائه شده را دنبال کنید.

  1. برای افزودن کتابخانه App Check، دستورالعمل‌های Firebase را دنبال کنید:
  2. بررسی برنامه را مقداردهی اولیه کنید.
    • اگر از App Attest استفاده می‌کنید، مستندات توسعه‌دهنده Firebase را برای App Attest دنبال کنید.

      دستورالعمل‌های Firebase App Check را دنبال کنید تا یک پیاده‌سازی از AppCheckProviderFactory ایجاد کنید و آن را به فایل AppDelegate خود اضافه کنید.

      مکان‌های Swift SDK برای iOS 

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

      سویفت 

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

      هدف-سی 

      YourAppCheckProviderFactory *providerFactory =
    [[YourAppCheckProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
    • اگر از Device Check استفاده می‌کنید، موارد زیر را به AppDelegate خود اضافه کنید:

      مکان‌های Swift SDK برای iOS 

      AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

      سویفت 

      AppCheck.setAppCheckProviderFactory(DeviceCheckProviderFactory())

      هدف-سی 

      [FIRAppCheck setAppCheckProviderFactory:providerFactory];

مرحله ۳: ارائه دهنده توکن را اضافه کنید

یک فایل با نام AppCheckTokenProvider (یا اگر از Objective-C استفاده می‌کنید، دو فایل با نام‌های AppCheckTokenProvider.h و AppCheckTokenProvider.m ) در سطح ریشه برنامه خود ایجاد کنید. دستورات import و تعریف کلاس زیر را اضافه کنید:

مکان‌های Swift SDK برای iOS 

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

مرحله ۴: مقداردهی اولیه APIهای Places و App Check

  1. در فایل AppDelegate خود، API مربوط به Places را مقداردهی اولیه کنید:

    مکان‌های Swift SDK برای iOS 

    PlacesClient.provideAPIKey("YOUR_API_KEY")

    سویفت 

    GMSPlacesClient.provideAPIKey("YOUR_API_KEY")

    هدف-سی 

    [GMSPlacesClient provideAPIKey:@"YOUR_API_KEY"];
  2. سپس، API مربوط به App Check را مقداردهی اولیه کنید:

    مکان‌های Swift SDK برای iOS 

    PlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

    سویفت 

    GMSPlacesClient.setAppCheckTokenProvider(AppCheckTokenProvider())

    هدف-سی 

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

مرحله ۵: فعال کردن اشکال‌زدایی (اختیاری)

اگر می‌خواهید برنامه خود را به صورت محلی توسعه داده و آزمایش کنید، یا آن را در یک محیط یکپارچه‌سازی مداوم (CI) اجرا کنید، می‌توانید یک نسخه اشکال‌زدایی از برنامه خود ایجاد کنید که از یک رمز اشکال‌زدایی برای به دست آوردن توکن‌های معتبر بررسی برنامه استفاده می‌کند. این به شما امکان می‌دهد از استفاده از ارائه‌دهندگان گواهی واقعی در نسخه اشکال‌زدایی خود اجتناب کنید.

برای تست برنامه خود در شبیه‌ساز یا روی یک دستگاه آزمایشی:

  • کارخانه‌ی ارائه‌دهنده‌ی اشکال‌زدایی App Check را ایجاد و تنظیم کنید.

    این نمونه کد، هر دو سناریوی اشکال‌زدایی و تولید را مدیریت می‌کند:

    مکان‌های Swift SDK برای iOS 

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

    سویفت 

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

    هدف-سی 

    if (targetEnvironment == simulator){

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

else {

YourAppCheckProviderFactory *providerFactory =
      [[YourAppCheckProviderFactory alloc] init];
[FIRAppCheck setAppCheckProviderFactory:providerFactory];
}
  • قابلیت گزارش‌گیری (logging) را در پروژه Xcode خود فعال کنید، برنامه را اجرا کنید و توکن اشکال‌زدایی محلی (local debug token) را در گزارش (log) پیدا کنید.
  • این توکن را به کنسول Firebase اضافه کنید.
  • برای اطلاعات و دستورالعمل‌های بیشتر، به مستندات App Check مراجعه کنید.

برای اجرای برنامه خود در محیط CI:

  • یک توکن اشکال‌زدایی در کنسول Firebase ایجاد کنید و آن را به مخزن کلید امن سیستم CI خود اضافه کنید.
  • در Xcode، یک متغیر محیطی با نام FIRAAppCheckDebugToken و مقدار $(APP_CHECK_DEBUG_TOKEN) (یا چیزی مشابه) به طرح آزمایش خود اضافه کنید.
  • در اسکریپت تست CI خود، توکن اشکال‌زدایی را به عنوان یک محیط ارسال کنید.

  • کارخانه‌ی ارائه‌دهنده‌ی اشکال‌زدایی App Check را ایجاد و تنظیم کنید.

    این نمونه کد، هر دو سناریوی اشکال‌زدایی و تولید را مدیریت می‌کند:

    مکان‌های Swift SDK برای iOS 

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

    سویفت 

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

    هدف-سی 

    #if DEBUG
id<FIRAppCheckProviderFactory> providerFactory =
    [[FIRAppCheckDebugProviderFactory alloc] init];
#else  // DEBUG
id<FIRAppCheckProviderFactory> providerFactory =
    [[YourAppCheckProviderFactory alloc] init];
#endif  // DEBUG
AppCheck.setAppCheckProviderFactory(providerFactory)
  • برای اطلاعات و دستورالعمل‌های بیشتر، به مستندات App Check مراجعه کنید.

مرحله ۶: درخواست‌های برنامه خود را رصد کنید و در مورد اجرای آنها تصمیم بگیرید

قبل از شروع اجرای قانون، باید مطمئن شوید که کاربران قانونی برنامه خود را مختل نمی‌کنید. برای انجام این کار، به صفحه معیارهای بررسی برنامه مراجعه کنید تا ببینید چند درصد از ترافیک برنامه شما تأیید شده، قدیمی یا غیرقانونی است. وقتی متوجه شدید که اکثر ترافیک شما تأیید شده است، می‌توانید اجرای قانون را فعال کنید.

برای اطلاعات و دستورالعمل‌های بیشتر، به مستندات Firebase App Check مراجعه کنید.