منع إساءة استخدام Gemini API باستخدام ميزة "فحص التطبيقات من Firebase"

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

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

• حماية كلٍّ من موفِّرَي "Gemini API": Gemini Developer API و Vertex AI Gemini API

• حماية جميع النماذج المتوافقة، سواء نماذج Gemini أو نماذج Imagen

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

اعتبارًا من أوائل يوليو 2026، ستفرض Firebase تلقائيًا App Check على AI Logic أثناء سير عمل الإعداد الموجَّه في Firebase وحدة التحكّم.

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

تتيح ميزة App Check أيضًا الحماية من إعادة استخدام الرموز، ما يعني أنّه لا يمكن استخدام الرمز المميّز لـ App Check إلا مرة واحدة.

ملخّص عالي المستوى لكيفية عمل App Check

باستخدام App Check، تستخدم الأجهزة التي تشغّل تطبيقك موفِّر شهادات للتطبيق أو الجهاز يتحقّق من أحد الشرطَين التاليَين أو كليهما:

• الطلبات واردة من تطبيقك الأصلي
• الطلبات واردة من جهاز أصلي لم يتم التلاعب به

يتم إرفاق هذه الشهادة بكل طلب يرسله تطبيقك باستخدام حزمة Firebase AI Logic SDK. عند فرض App Check، سيتم رفض الطلبات الواردة من البرامج العميلة التي ليس لديها شهادة صالحة، بالإضافة إلى أي طلب وارد من تطبيق أو منصة لم تمنحها الإذن.

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

يمكنك العثور على معلومات مفصّلة عن App Check في مستنداتها، بما في ذلك الحصص والحدود.

إعداد App Check

توفّر مستندات App Check أوصافًا تفصيلية لموفِّري الشهادات بالإضافة إلى تعليمات مفصّلة عن التنفيذ.

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

1. اختَر موفِّر شهادات واتّبِع تعليمات التنفيذ على الروابط التالية:

   • منصات Apple: DeviceCheck أو App Attest
   • Android: Play Integrity
   • الويب: reCAPTCHA Enterprise
   • Flutter: تتيح هذه المنصة استخدام جميع الموفِّرين التلقائيين أعلاه.
     إذا كنت تستخدم إصدارات أقدم من المكوّن الإضافي، يُرجى الاطّلاع على الملاحظة حول عملية إنشاء مثيل خاصة أدناه. لـ Flutter وميزة App Check.
   • Unity: تدعم جميع الموفِّرين التلقائيين أعلاه

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

2. (مطلوب) فعِّل فرض ميزة App Check قبل إرسال تطبيقك إلى نظام تحكّم في رمز المصدر متاح للجميع أو مشاركة تطبيقك أو إتاحته للجميع.

3. (ننصحك بذلك) حسِّن الحماية من خلال إضافة الحماية من إعادة استخدام الرموز، ما يعني أنّه لا يمكن استخدام الرمز المميّز لميزة "App Check" إلا مرة واحدة.

4. لأغراض التطوير المحلي عند فرض App Check، عليك إعداد App Check موفِّر تصحيح الأخطاء لتجاوز الشهادة مع الحفاظ على فرض App Check. يُرجى الاطّلاع على تعليمات الإعداد لمنصتك: iOS+ | Android | الويب | Flutter | Unity.

يجب إجراء عملية إنشاء مثيل خاصة لـ Flutter في حال استخدام إصدارات أقدم من المكوّن الإضافي

انقر على موفِّر Gemini API للاطّلاع على المحتوى والرمز البرمجي الخاصَّين بالموفِّر على هذه الصفحة. Gemini Developer API Vertex AI Gemini API

لا تكون عملية إنشاء المثيل الخاصة هذه مطلوبة إلا إذا كان تطبيقك يستخدم المكوّن الإضافي firebase_ai لإصدار Flutter ‏3.11.0 أو إصدارًا أقدم (قائمة مواد الإصدار 4.12.0 أو إصدارًا أقدم). إذا كان تطبيقك يستخدم إصدارًا أحدث من المكوّن الإضافي، لن تكون عملية إنشاء المثيل الخاصة هذه مطلوبة.

ملاحظة: تنصح Firebase باستخدام أحدث إصدارات حِزم SDK والمكوّنات الإضافية والأدوات حتى تتمكّن من الوصول إلى أحدث الميزات وإصلاحات الأخطاء وما إلى ذلك.

إذا فعّلت فرض App Check، عليك في تطبيقات Flutter التي تستخدم إصدارات أقدم من المكوّن الإضافي، تمرير App Check بشكلٍ صريح أثناء عملية إنشاء المثيل، على النحو التالي:

// ...

// During instantiation, enable usage of limited-use tokens
final ai = await FirebaseAI.googleAI(
  // For Flutter plugin v3.11.0 or lower (BoM v4.12.0 or lower), pass in App Check explicitly.
  appCheck: FirebaseAppCheck.instance,
  useLimitedUseAppCheckTokens: true,
);

// ...

تحسين الحماية من خلال إضافة الحماية من إعادة استخدام الرموز

ننصحك باستخدام أحدث إصدارات حِزم SDK، ولكن تأكَّد من استخدام أحد هذه الإصدارات على الأقل لاستخدام الحماية من إعادة استخدام الرموز: منصات Apple الإصدار 12.2.0 أو إصدار أحدث | قائمة مواد الإصدار لنظام التشغيل Android ‏34.14.0 أو إصدار أحدث (App Check الإصدار 19.1.0 أو إصدار أحدث) | الويب الإصدار 12.14.0 أو إصدار أحدث | Flutter الإصدار 4.15.0 أو إصدار أحدث (App Check الإصدار 4.10.0 أو إصدار أحدث) | Unity الإصدار 13.12.0 أو إصدار أحدث

تستخدم App Check تلقائيًا الرموز المميّزة للجلسة التي تتراوح مدة بقائها بين 30 دقيقة و7 أيام، ويمكنك ضبطها. تخزّن حزمة SDK لميزة App Check هذه الرموز المميّزة للجلسة مؤقتًا، ويتم إرسالها مع الطلبات من تطبيقك، ويمكن إعادة استخدامها إلى أن تنتهي مدة بقائها. يُعد استخدام الرموز المميّزة للجلسة حماية أساسية.

مع ذلك، يمكنك تحسين الحماية بما يتجاوز هذه الحماية الأساسية من خلال فرض الحماية من إعادة استخدام الرموز، التي تستخدم الرموز المميّزة المحدودة الاستخدام بدلاً من ذلك. عند فرض الحماية من إعادة استخدام الرموز، يحدث ما يلي:

• App Check ستحظر الطلبات الموجَّهة إلى Firebase AI Logic التي تستخدم الرموز المميّزة للجلسة. بدلاً من ذلك، App Check لن تسمح ميزة "التحقّق من التطبيق" إلا بطلب واحد إلى Firebase AI Logic إذا كان يستخدم رمزًا مميّزًا جديدًا محدود الاستخدام.

• بعد التحقّق من الرمز المميّز المحدود الاستخدام، يتم استخدامه بحيث لا يمكن استخدامه إلا مرة واحدة، ما يمنع الهجمات التي تهدف إلى إعادة استخدام الرموز.

• تنشئ حزمة SDK لميزة App Check رمزًا مميّزًا جديدًا محدود الاستخدام لـ كل طلب. يُرجى العِلم أنّ هذه العملية يمكن أن تؤثّر في طلباتك من خلال إضافة بعض وقت الاستجابة وأحيانًا التكلفة (حسب موفِّر الشهادات).

إعداد الحماية من إعادة استخدام الرموز وفرضها

انقر على موفِّر Gemini API للاطّلاع على المحتوى والرمز البرمجي الخاصَّين بالموفِّر على هذه الصفحة. Gemini Developer API Vertex AI Gemini API

إليك كيفية إعداد الحماية من إعادة استخدام الرموز وفرضها:

1. إذا لم يسبق لك ذلك، عليك تنفيذ App Check و تفعيل فرض App Check لتطبيقك.

2. فعِّل استخدام الرموز المميّزة المحدودة الاستخدام.

   في تطبيقك أثناء عملية إنشاء المثيل، اضبط المعلمة useLimitedUseAppCheckTokens على true:

   Swift

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   let ai = FirebaseAI.firebaseAI(
     backend: .googleAI(),
     useLimitedUseAppCheckTokens: true
   )
   
   // ...
   
   

   Kotlin

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   val ai = Firebase.ai(
     backend = GenerativeBackend.googleAI(),
     useLimitedUseAppCheckTokens = true
   )
   
   // ...
   
   

   Java

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   FirebaseAI ai = FirebaseAI.getInstance(
     /* backend: */ GenerativeBackend.googleAI(),
     /* useLimitedUseAppCheckTokens: */ true
   );
   
   // ...
   
   

   Web

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   const ai = getAI(firebaseApp, {
     backend: new GoogleAIBackend(),
     useLimitedUseAppCheckTokens: true
   });
   
   // ...
   
   

   Dart

   
   // ...
   
   // During instantiation, enable usage of limited-use tokens
   final ai = await FirebaseAI.googleAI(
     useLimitedUseAppCheckTokens: true,
   );
   
   // ...
   
   

   Unity

   // ...
   
   // During instantiation, enable usage of limited-use tokens
   var ai = FirebaseAI.GetInstance(
     useLimitedUseAppCheckTokens: true
   );
   
   // ...
   

   ملاحظة: ننصحك بإعداد الرموز المميّزة المحدودة الاستخدام لتكون مَعلمة في Firebase Remote Config حتى تتمكّن من التحكّم في إعدادها عن بُعد بدلاً من أن تكون مبرمَجة في تطبيقك. مزيد من المعلومات عن استخدام Remote Config.

3. افرض الحماية من إعادة استخدام الرموز.

   1. في قاعدة رموز تطبيقك، تأكَّد من أنّك فعّلت استخدام الرموز المميّزة المحدودة الاستخدام (راجِع الخطوة السابقة).

   2. في وحدة تحكّم Firebase، انتقِل إلى الأمان > التحقّق من التطبيق.

   3. وسِّع عرض المقاييس لـ Firebase AI Logic.

   4. تأكَّد من الحماية الأساسية هو مفروض، ثم انقر على متابعة.

   5. بالنسبة إلى الحماية من إعادة استخدام الرموز، اختَر غير مفروضة (للمراقبة فقط) أو مفروضة.

      ضع في اعتبارك ما يلي لتحديد وقت فرض الحماية من إعادة استخدام الرموز:

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

      • يمكنك مراقبة المقياس لم يتم التحقّق منه: تم إعادة استخدام الرمز المميّز على وجه التحديد، وهو عدد الطلبات التي تتضمّن رمزًا مميّزًا سبق استخدامه في طلب سابق. يمكنك مراقبة هذا المقياس في وحدة تحكّم Firebase (انتقِل إلى الأمان > التحقّق من التطبيق > علامة التبويب واجهات برمجة التطبيقات).

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

ملاحظة: يُرجى العِلم بما يلي إذا فعّلت فقط استخدام الرموز المميّزة المحدودة الاستخدام ولم تفرض الحماية من إعادة استخدام الرموز:

• تكون مدة بقاء الرموز المميّزة المحدودة الاستخدام 5 دقائق فقط، ولا يمكن تعديلها (على عكس الرموز المميّزة للجلسة). عندما لا يتم فرض الحماية من إعادة استخدام الرموز ، تكون الرموز المميّزة المحدودة الاستخدام مشابهة للرموز المميّزة للجلسة من حيث إمكانية إعادة استخدامها إلى أن تنتهي مدة بقائها.
• على الرغم من أنّ الرموز المميّزة المحدودة الاستخدام تكون صالحة لمدة 5 دقائق، ستظل حزمة SDK تنشئ رمزًا مميّزًا جديدًا لـ كل طلب. أيضًا، تخزّن حِزم SDK الرموز المميّزة المحدودة الاستخدام مؤقتًا.
• عندما لا يتم فرض الحماية من إعادة استخدام الرموز، App Check لن تحظر الطلبات الموجَّهة إلى Firebase AI Logic التي تستخدم رموزًا مميّزة صالحة للجلسة.

فهم كيفية دمج Firebase AI Logic مع App Check

لاستخدام حِزم Firebase AI Logic SDK، يجب تفعيل Firebase AI Logic API‏ (firebasevertexai.googleapis.com) في مشروعك على Firebase. وذلك لأنّ الطلبات التي ترسلها حِزم Firebase AI Logic SDK تُرسَل أولاً إلى خادم Firebase AI Logic ، الذي يعمل كبوابة وكيل حيث يتم التحقّق من Firebase App Check قبل السماح للطلب بالانتقال إلى خلفية موفِّر "Gemini API" الذي اخترته وواجهات برمجة التطبيقات للوصول إلى نماذج Gemini وImagen.

(اختياري) فرض App Check بدون موفِّر شهادات للإنتاج (موفِّر تصحيح الأخطاء فقط)

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

تنبيه: لا يكون هذا الإعداد مخصّصًا إلا للتطبيقات التي يتم إعدادها قبل الإنتاج. قبل إطلاق تطبيقك للمستخدمين النهائيين، عليك اتّباع التعليمات الواردة سابقًا في هذه الصفحة لإعداد موفِّر شهادات للإنتاج واستخدامه (مثل App Attest أو Play Integrity أو reCAPTCHA Enterprise).

1. تحقَّق مما إذا كانت ميزة App Check مفروضة حاليًا على AI Logic.

   1. في وحدة تحكّم Firebase، انتقِل إلى علامة التبويب الأمان > التحقّق من التطبيق > واجهات برمجة التطبيقات.

   2. ابحث عن صف Firebase AI Logic. إذا كان مكتوبًا Unenforced، عليك متابعة الخطوات المتبقية من هذه التعليمات.

2. انقر على صف Firebase AI Logic، وستظهر لك رسوم بيانية للمقاييس. أسفل هذه الرسوم البيانية، انقر على إعداد.

3. في الشاشة الأولى من مربّع الحوار (الحماية الأساسية)، اختَر مفروضة، ثم انقر على متابعة.

4. في الشاشة التالية (الحماية من إعادة استخدام الرموز)، اختَر غير مفعّلة. يمكنك إعداد ذلك في وقت لاحق والرجوع إلى سير عمل الإعداد هذا. انقر على متابعة.

   ملاحظة: إذا كانت الرموز المميّزة المحدودة الاستخدام مفعّلة حاليًا في تطبيقك، يمكنك اختيار أحد خيارات الحماية من إعادة استخدام الرموز بدلاً من إيقافها.

5. في الشاشة الأخيرة، راجِع الاعتبارات الخاصة بفرض App Check للتأكّد من أنّك مستعد لفرض App Check. إذا كنت مستعدًا، انقر على متابعة.

   ليس عليك تسجيل تطبيقاتك إذا كنت تريد فقط فرض App Check واستخدام موفِّر تصحيح الأخطاء فقط مع AI Logic في تطبيق يتم إعداده قبل الإنتاج. ومع ذلك، عندما تكون مستعدًا لإطلاق تطبيقك للمستخدمين النهائيين، عليك تسجيل تطبيقاتك كجزء من إعداد موفِّر شهادات للإنتاج (مثل App Attest أو Play Integrity أو reCAPTCHA Enterprise).

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

   للحصول على تفاصيل حول إعداد موفِّر تصحيح الأخطاء، يُرجى الاطّلاع على التعليمات الخاصة بـ منصتك: iOS+ | Android | الويب | Flutter | Unity.

ملاحظة: يمكنك استخدام سير عمل مشابه في وحدة تحكّم Firebase لإيقاف فرض ميزة App Check:

1. انقر على صف Firebase AI Logic، وستظهر لك رسوم بيانية للمقاييس. أسفل هذه الرسوم البيانية، انقر على إعداد.
2. في الشاشة الأولى من مربّع الحوار (الحماية الأساسية)، اختَر غير مفروضة (للمراقبة فقط)، ثم انقر على متابعة.
3. في الشاشة التالية (الحماية من إعادة استخدام الرموز)، اختَر غير مفعّلة، ثم انقر على متابعة.
4. في الشاشة الأخيرة، انقر على متابعة لإيقاف فرض ميزة App Check.

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