في السنوات الأخيرة، صار من النادر أن تجد تطبيقًا لا يتكامل مع خدمات جوجل. من التقويم (Calendar) إلى البريد (Gmail) وصولًا إلى يوتيوب (YouTube)، يعتمد ملايين المستخدمين يوميًا على هذه الخدمات. والجميل أننا كمطوّرين نستطيع دمجها بسهولة داخل تطبيقاتنا باستخدام Flutter وحزمة googleapis.

لماذا Google APIs مع Flutter؟

تخيل أنك تبني تطبيق “منظم مهام يومية”:

• تريد أن تعرض للمستخدم أحداثه من تقويم جوجل.
• أو أن تعرض آخر فيديوهاته المفضلة من يوتيوب.
• أو حتى تقرأ بريده الوارد في Gmail.

بدلًا من إعادة اختراع العجلة، جوجل تعطيك APIs جاهزة، كل ما عليك هو الربط والمصادقة. النتيجة: توفير وقت وجهد، وثقة أكبر من المستخدم لأن تطبيقك يتعامل مع خدمات يعرفها ويستخدمها يوميًا.

الخطوات الرئيسية لدمج Google APIs في Flutter

رحلتنا تنقسم إلى خمس مراحل، وكل مرحلة ضرورية:

1. اختيار الـ API المناسب
2. تمكين الـ API من Google Cloud
3. مصادقة المستخدم (Sign in with Google)
4. الحصول على عميل HTTP مصادق (Authenticated HTTP client)
5. تنفيذ وظائف الـ API داخل التطبيق

لنأخذها واحدة تلو الأخرى مع أمثلة عملية.

1. اختيار الـ API المناسب

الحزمة googleapis على pub.dev توفر عشرات الخدمات. كل خدمة تأتي كمكتبة مستقلة باسم مثل:

• calendar_v3 للتقويم
• gmail_v1 للبريد
• youtube_v3 ليوتيوب

لكل مكتبة فئة رئيسية تنتهي بـ Api مثل YouTubeApi. هذه الفئة تمنحك:

• طرق للتعامل مع الخدمة.
• قائمة Scopes تحدد صلاحيات الوصول (قراءة فقط؟ تعديل؟).

📌 مثال عملي (استيراد YouTube API):

import 'package:googleapis/youtube/v3.dart';

2. تمكين الـ API من Google Cloud

لن يعمل أي API إلا إذا فعّلته من لوحة تحكم Google Cloud.
مثال: لتفعيل YouTube Data API v3:

• اذهب إلى Google Cloud Console
• اضغط “Enable”

بعدها ستحصل على API key أو بيانات OAuth (للمصادقة).

⚠️ إذا نسيت هذه الخطوة، سترى خطأ شائع: API not enabled.

3. مصادقة المستخدم: الخطوة الأمنية الأهم

نستخدم حزمة google_sign_in. هذه الحزمة:

• تتيح تسجيل الدخول بحساب جوجل.
• تعيد لك المستخدم الحالي.

📌 الكود الأساسي:

import 'package:google_sign_in/google_sign_in.dart';

final _googleSignIn = GoogleSignIn();

Future<void> handleSignIn() async {
  try {
    final user = await _googleSignIn.signIn();
    print("مرحبًا ${user?.displayName}");
  } catch (e) {
    print("خطأ في تسجيل الدخول: $e");
  }
}

4. الحصول على عميل HTTP مصادق

بعد تسجيل الدخول، تحتاج إلى عميل HTTP آمن لإرسال الطلبات.
نستخدم الحزمة extension_google_sign_in_as_googleapis_auth.

📌 الكود:

import package:extension_google_sign_in_as_googleapis_auth/extension_google_sign_in_as_googleapis_auth.dart';

final client = await _googleSignIn.authenticatedClient();
final youTubeApi = YouTubeApi(client);

الآن أي طلب ترسله سيكون مصدق وآمن.

5. استخدام الـ API فعليًا

هنا تبدأ المتعة 🎉
مثلاً: عرض الفيديوهات المفضلة لمستخدم يوتيوب:

final favorites = await youTubeApi.playlistItems.list(
  ['snippet'],
  playlistId: 'LL', // قائمة الإعجابات
);

for (var item in favorites.items!) {
  print(item.snippet?.title);
}

نصائح ذهبية لتجنب الأخطاء

• استخدم أقل Scope ممكن: إذا كنت تحتاج “قراءة فقط”، لا تطلب إذن “تعديل”. هذا يكسب ثقة المستخدم.
• جرّب دائمًا على Emulator قبل النشر.
• استخدم try-catch لتفادي انهيار التطبيق عند فشل الشبكة أو انتهاء صلاحية التوكين.

ممتاز 👌
خليني أحول الإجابة السابقة إلى مقال مدوّنة مكمل للمقال الأول عن Google APIs، بحيث يكون مكمّل ووافي يوضح الآلية المالية والعملية بوضوح.

من يتحمل التكلفة عند استخدام Google APIs في Flutter؟ المطور أم المستخدم؟

عند البدء في دمج Google APIs داخل تطبيقك المبني بـ Flutter، غالبًا سيتبادر إلى ذهنك سؤال مهم:

هل يتم احتساب تكلفة استخدام الـ API من حساب المطور (صاحب المشروع في Google Cloud) أم من حساب المستخدم الذي يسجل دخوله بالتطبيق؟

هذا سؤال منطقي جدًا، خصوصًا أن التطبيقات عادةً تتعامل مع بيانات شخصية (مثل Gmail أو YouTube) لكنها تُشغَّل من خلال API key أو OAuth credentials خاصة بالمطور. في هذا المقال، نوضّح الصورة كاملة خطوة بخطوة.

ملحوظة: أين تُحسب التكلفة؟

• التكلفة دائمًا تُحسب على المشروع (Project) الذي أنشأته أنت في Google Cloud Console.
• أي طلب (Request) يتم عبر API key أو OAuth token يصدر من مشروعك أنت، وبالتالي يدخل في الحصة (Quota) الخاصة بك كمطور.
• لا يوجد شيء اسمه “خصم من رصيد المستخدم”؛ المستخدم يمنحك فقط إذن الوصول لبياناته.

ما دور المستخدم الذي يسجل الدخول بحسابه؟

المستخدم النهائي (الذي يفتح تطبيقك ويسجل دخولًا بحساب Google الخاص به):

• لا يتحمل أي تكلفة مالية.
• فقط يمنح إذنًا للتطبيق عبر OAuth Scopes لتحديد الصلاحيات (مثل: قراءة تقويمه، الاطلاع على بريده، أو عرض قوائم تشغيل يوتيوب).
• هذا يعني أن البيانات تخصه، لكن الحصة تُخصم من مشروعك أنت.

الفرق بين “الحصة (Quota)” و”المصادقة (Authentication)”

مثال عملي لتوضيح الصورة

لنفترض أنك بنيت تطبيق Flutter يعرض للمستخدم الفيديوهات المفضلة من يوتيوب:

1. المطور (أنت):
   • أنشأت مشروعًا على Google Cloud.
   • فعّلت YouTube Data API v3.
   • حصلت على OAuth credentials.
2. المستخدم (أحمد):
   • يفتح التطبيق ويسجل دخولًا عبر Google Sign-In.
   • يوافق على منح صلاحية “youtube.readonly”.
3. عند التنفيذ:
   • التطبيق يطلب الفيديوهات من API.
   • البيانات تأتي من حساب أحمد.
   • الطلب يُحسب من حصة مشروعك أنت (وليس من حساب أحمد).

ماذا يعني هذا للمطور؟

• تحتاج أن تراقب لوحة الحصص (Quotas) في Google Cloud Console.
• إذا تجاوزت الحد المجاني، ستُحاسب أنت كمطور.
• لذلك:
  • اضبط القيود (Limits).
  • لا تطلب صلاحيات أكثر مما تحتاج.
  • فكر في نموذج ربحي إذا كان تطبيقك يستهلك استدعاءات كثيرة.

هذه القاعدة تنطبق على جميع خدمات Google APIs (YouTube, Gmail, Calendar, Drive … إلخ).

إذا كنت تبني تطبيقًا يتطلب آلاف أو ملايين الطلبات يوميًا، فمن المهم أن تخطط جيدًا لاستهلاك الحصص وأن تتأكد من أن نموذج عملك يغطي هذه التكاليف.

الخاتمة

دمج Google APIs في Flutter ليس رفاهية، بل خطوة استراتيجية لجعل تطبيقك أقوى وأكثر فائدة.
سواء أردت التعامل مع Calendar، Gmail، أو YouTube، فالخطوات التي تعلمتها هنا ستفتح لك أبوابًا واسعة.

ابدأ اليوم بتجربة واحدة من هذه الـ APIs، وشاركنا تجربتك. ومع كل مشروع جديد، ستشعر أنك تبني تطبيقًا عالميًا بخدمات يعرفها كل مستخدم.