دليل إعداد Google Maps في Flutter على Android وiOS: تفعيل SDK وإضافة مفاتيح مقيدة وتشخيص الخريطة الفارغة، مع مثال عرض بسيط.
ابدأ بخريطة دون صلاحيات الموقع
إعداد Google Maps في Flutter يعني تجهيز الحزمة والخدمة الخاصة بكل منصة ثم عرض GoogleMap بمركز ثابت. عرض الخريطة وحده لا يحتاج طلب موقع الجهاز. اختبر هذا السيناريو أولًا؛ إضافة الأذونات والتتبع والبحث في خطوة واحدة تجعل تشخيص الأخطاء أصعب. المثال أدناه يعرض القاهرة كموقع تجريبي ولا يجمع بيانات المستخدم أو يفتح طلب GPS تلقائيًا.
اختيار نسخة الحزمة المناسبة
استُخدمت google_maps_flutter 2.18.1 في مشروع التحقق لهذه المراجعة، لأنها متوافقة مع Dart المتاح فيه. قد تتطلب نسخة أحدث حدًا أعلى من Flutter أو Dart؛ لا تعالج خطأ محلل الاعتماديات بتعديل الملفات الداخلية للحزمة. ثبّت إصدارًا يوافق بيئة مشروعك وراجع متطلبات Android وiOS في README الخاص به، ثم احتفظ بملف pubspec.lock في تطبيقك لتكرار البناء نفسه.
تفعيل الخدمات ومفاتيح المنصات
أنشئ مشروع Google Cloud وفعل Maps SDK for Android وMaps SDK for iOS وفق المنصات التي ستدعمها، وأكمل متطلبات الفوترة المطلوبة للخدمة. استخدم مفتاحًا لكل منصة مع تقييد واجهات API وتقييد التطبيق المناسب. المفتاح داخل تطبيق العميل قابل للاستخراج، لذلك وجوده في ملف إعداد محلي لا يجعله سريًا؛ القيود ومراقبة الاستخدام هي ما يقلل إساءة استعماله.
إعداد Android بشكل صحيح
ضع meta-data باسم com.google.android.geo.API_KEY داخل application في AndroidManifest.xml. احتفظ بمعرف التطبيق الفعلي ومواصفات التوقيع عند تقييد المفتاح، واختبر نسخة debug ونسخة release لأن شهادتيهما قد تختلفان. راجع اتصال الشبكة وخدمات Google Play في جهاز التجربة. لا تضف ACCESS_BACKGROUND_LOCATION لمجرد تشغيل خريطة؛ هذا إذن لوظيفة مختلفة وله متطلبات إضافية لا يحتاجها العرض الثابت.
إعداد iOS دون إتلاف القالب
اتبع تكامل الإصدار المستخدم في مشروع Runner، واستورد GoogleMaps ثم مرر المفتاح إلى GMSServices.provideAPIKey ضمن موضع التهيئة الذي تحدده وثائق الحزمة. لا تستبدل AppDelegate كاملًا بنص قديم، فقد يحتوي مشروعك على إعدادات تسجيل إضافات أو دورة حياة مختلفة. المفتاح المقيد باسم الحزمة يجب أن يطابق Bundle Identifier الفعلي. احتفظ بتهيئة Flutter والإضافات الموجودة في القالب.
تفسير الخريطة البيضاء أو الفارغة
إذا ظهرت واجهة GoogleMap دون البلاطات، راجع تفعيل SDK والمفتاح والقيود والفوترة ثم سجل أخطاء المنصة. تأكد أن الخريطة لها مساحة محددة، مثل وضعها داخل Expanded عند استخدامها في Column. اختبر على جهاز آخر وشبكة أخرى لتفصل خطأ الإعداد عن الاتصال. لا تنقل مفتاح خدمات الويب إلى التطبيق كحل سريع لمشكلة مفتاح Android أو iOS.
إضافة الموقع الحالي لاحقًا
بعد ظهور الخريطة الثابتة، أضف موقع المستخدم وفق إدارة الإذن وقراءة الموقع في Flutter. تفعيل myLocationEnabled قبل منح الإذن قد ينتج مشكلة منصة، لذلك اجعل حالة الواجهة مرتبطة بالإذن الفعلي. وإذا أردت شكلًا مختلفًا للعلامة فانتقل إلى تخصيص أيقونة Marker؛ إعداد الأيقونة لا يصلح مشكلة خريطة لا تستطيع تحميل بياناتها.
قائمة تحقق للإصدار النهائي
تحقق من قيود كل مفتاح ومن اسم الحزمة وشهادة التوقيع في النسخة المنشورة. اختبر عدم الاتصال وإعادة الدخول للشاشة وتغير حجم النافذة، وتأكد أن عناصر الواجهة لا تغطي نسب الخريطة وحقوق مزودها. احتفظ برسالة خطأ قابلة للفهم عند تعذر العرض. البحث والاتجاهات خدمات مستقلة عن عرض الخريطة؛ لا تفعلها أو تطلبها في الكود إن لم تكن جزءًا من احتياج التطبيق.
الإعداد أو عقد التكامل المطلوب
طبّق الجزء المناسب على مشروعك بعد مراجعة إصدار الحزمة والمنصة؛ قيم الإعداد هنا توضيحية وليست مفاتيح صالحة أو خدمة خلفية منشورة.
<!-- Inside application in android/app/src/main/AndroidManifest.xml -->
<meta-data android:name="com.google.android.geo.API_KEY"
android:value="YOUR_RESTRICTED_ANDROID_KEY" />
// In the iOS initialization described by your package version:
import GoogleMaps
// GMSServices.provideAPIKey("YOUR_RESTRICTED_IOS_KEY")مثال الكود المراجع
الكود التالي يوضح نطاق الدرس ولا يغني عن إعداد المنصة أو الخدمات المذكورة أعلاه. اختُبر بتحليل Dart واختبارات المنطق المناسبة؛ تشغيل GPS والخرائط والخدمات الخارجية يحتاج جهازًا وإعداداتك الخاصة.
import 'package:flutter/material.dart';
import 'package:google_maps_flutter/google_maps_flutter.dart';
class BasicGoogleMap extends StatelessWidget {
const BasicGoogleMap({super.key});
@override
Widget build(BuildContext context) => const Scaffold(
body: GoogleMap(initialCameraPosition: CameraPosition(
target: LatLng(30.0444, 31.2357), zoom: 12)),
);
}






