متغیرهای ابری با Google Drive
با عملکردهای ذخیره متغیر در فضای ابری و دریافت متغیر از فضای ابری، داده‌های انتخاب‌شدهٔ کاربر مانند تنظیمات، پیشرفت بازی و یادداشت‌ها را در Google Drive خودش نگه دارید و پس از نصب دوباره یا روی گوشی دیگر بازیابی کنید.
متن، عدد صحیح، عدد اعشاری، بولی و JSON پشتیبانی می‌شوند. برای چند دادهٔ مرتبط، یک متغیر JSON بسازید.
این نسخه فقط در خروجی جدید اندروید اجرا می‌شود. پیش‌نمایش پنل و خروجی وب، iOS و دسکتاپ به Drive متصل نمی‌شوند و نتیجهٔ unsupported می‌دهند. افزودن این قابلیت یا تغییر شناسهٔ اتصال به ساخت و نصب خروجی جدید نیاز دارد؛ انتشار آنلاین به‌تنهایی SDK تازه را به اپ قدیمی اضافه نمی‌کند.
محل ذخیره و حساب کاربر
داده در پوشهٔ خصوصی appDataFolder در Drive حساب گوگل انتخاب‌شده ذخیره می‌شود. فایل در فهرست معمول Drive دیده نمی‌شود و اطلاعات از سرور اپ‌ادیتور عبور نمی‌کند. رمز حساب گوگل و توکن دسترسی وارد متغیرهای اپ یا فایل پشتیبان نمی‌شوند.
بازیابی به همان اپ، همان حساب گوگل و همان کلید ابری نیاز دارد. ورود به حساب داخلی اپ، به‌تنهایی اتصال گوگل را برقرار نمی‌کند. برای چند پروفایل داخلی روی یک حساب گوگل، کلیدهای متفاوت انتخاب کنید.
طبق شرایط رسمی Drive API، پشتیبان‌گیری از محتوای کاربر یا اپ در Drive به رضایت کتبی قبلی گوگل نیاز دارد. دسترسی محدود drive.appdata این شرط را خودبه‌خود رفع نمی‌کند. پیش از انتشار عمومی، شرایط استفادهٔ موردنظر خود را با گوگل تعیین تکلیف کنید.
تنظیم اتصال گوگل
این تنظیمات را سازندهٔ اپ یک بار انجام می‌دهد؛ کاربران داخل اپ حساب خودشان را انتخاب می‌کنند.
- در Google Cloud Console پروژه‌ای مختص همین اپ بسازید. برای اپ‌های مستقل، پروژه‌های مستقل به کار ببرید؛ برای نسخه‌های جدید همان اپ، پروژهٔ قبلی را حفظ کنید.
- Google Drive API را فعال کنید.
- در Google Auth Platform، اطلاعات نام و تماس اپ، مخاطبان، صفحهٔ حریم خصوصی و تنظیمات انتشار را تکمیل کنید. دسترسی موردنیاز
https://www.googleapis.com/auth/drive.appdataاست؛ دسترسی کامل به Drive لازم نیست. در حالت Testing، حساب‌های آزمایشی را در Test users اضافه کنید. - یک کلاینت OAuth از نوع Android بسازید: نام بسته دقیقاً مطابق تنظیمات اپ و SHA-1 مطابق گواهی امضای خروجی نصب‌شده باشد.
- در همان پروژه یک کلاینت OAuth از نوع Web application ایجاد و Client ID آن را کپی کنید؛ معمولاً به
apps.googleusercontent.comختم می‌شود. - در پنل، تنظیمات پروژه ← فضای ابری (Google Drive)، این مقدار را در Web OAuth client ID وارد کنید. Client Secret را وارد نکنید.
- تنظیمات را ذخیره و خروجی جدید اندروید را بسازید و نصب کنید.
این روش به بارگذاری google-services.json یا فعال کردن سرویس اعلان نیاز ندارد. راهنمای رسمی اتصال Flutter
اثرانگشت گواهی امضا
برای کی‌استوری که واقعاً اپ را با آن امضا می‌کنید، می‌توانید از ابزار Java استفاده کنید:
keytool -list -v -keystore YOUR_KEYSTORE.jks -alias YOUR_ALIAS
رمز را در پاسخ به درخواست ابزار وارد کنید؛ آن را در کد، متغیر یا پیام عمومی قرار ندهید. اگر از Play App Signing استفاده می‌کنید، SHA-1 گواهی امضای اپ در Google Play Console را نیز ثبت کنید؛ گواهی Upload ممکن است با گواهی نصب‌شده متفاوت باشد.
عملکردها و کلید ابری
| عملکرد | ورودی | رفتار |
|---|---|---|
| ذخیره متغیر | متغیر مبدأ و کلید ابری | ذخیره یا جایگزینی مقدار همان کلید |
| دریافت متغیر | کلید ابری و متغیر مقصد | دریافت، بررسی و نوشتن در مقصد |
کلید از نام متغیر مستقل است: gameProgress را با کلید progress ذخیره و بعداً در restoredProgress دریافت کنید.
کلید پس از جایگذاری متغیرها باید ۱ تا ۹۶ کاراکتر و شامل حروف لاتین، عدد، نقطه، خط تیره یا زیرخط باشد؛ کاراکتر اول حرف یا عدد است. مثال: progress، settings_v1 یا progress_{{profileId}}. کلید خالی، فاصله و حروف فارسی پذیرفته نمی‌شوند.
مثال: بازیابی روی گوشی جدید
گوشی اول
- با ایجاد متغیر،
gameProgressرا از نوع JSON در حافظهٔ دستگاه بسازید؛ گزینهٔ «اگر قبلاً ایجاد شده کاری انجام نشود» روشن بماند. - پس از پیشرفت کاربر، مقدار آن مثلاً چنین باشد:
{"level":12,"score":4500,"sound":true}
- دکمهٔ «ذخیره پیشرفت» را به عملکرد ذخیره متصل کنید: مبدأ
gameProgress، کلیدprogress، متغیر نتیجهcloudResult. - برای موفقیت پیام «پیشرفت ذخیره شد» و برای خطا پیام
{{cloudResult.error}}را تنظیم کنید. - کاربر حساب گوگل را انتخاب و دسترسی را تأیید می‌کند؛ پیام موفقیت پس از تأیید ذخیره توسط Drive اجرا می‌شود.
گوشی دوم
- کاربر همان اپ را نصب و «بازیابی پیشرفت قبلی» را انتخاب می‌کند.
- عملکرد دریافت را با کلید
progress، مقصدgameProgressو نوع ساخت مقصد «حافظه دستگاه» اجرا کنید. - کاربر همان حساب گوگل قبلی را انتخاب می‌کند. برای تغییر حساب، گزینهٔ «انتخاب دوباره حساب» را روشن کنید.
- اپ فایل را در همان حساب جست‌وجو می‌کند؛ هیچ شناسهٔ فایل یا داده‌ای از گوشی قبلی لازم نیست.
- پس از دریافت معتبر،
gameProgressبه مقدار مرحلهٔ ۱۲ تغییر می‌کند و ویجت‌های متصل به آن به‌روز می‌شوند. - داده در حافظهٔ گوشی دوم هم باقی می‌ماند؛ خواندن محلی بعدی به اینترنت نیاز ندارد. ذخیرهٔ ابری بعدی با اجرای دوبارهٔ عملکرد ذخیره انجام می‌شود.
در نصب تازه، مرحلهٔ ۱ را پیش از ارائهٔ گزینهٔ بازیابی، خودکار روی کلید progress ذخیره نکنید. ابتدا «بازیابی قبلی» یا «شروع جدید» را پیشنهاد دهید. اجرای دریافت، دادهٔ ابری را بازنویسی نمی‌کند.
متغیر مقصد
- مقصد، نام یک متغیر اصلی و غیرسیستمی است؛ مسیرهایی مانند
profile.progressبرای مقصد دریافت پذیرفته نمی‌شوند. ابتدا JSON را در متغیر اصلی دریافت و سپس مسیر آن را بخوانید. - اگر مقصد موجود باشد، محل ذخیرهٔ آن حفظ می‌شود. انتخاب حافظهٔ دستگاه یا موقت فقط برای ساخت مقصد تازه است.
- متن‌هایی مانند
00123وfalseبه عدد یا بولی تبدیل نمی‌شوند. - نوع ناسازگار با مقصد، خطای
type_mismatchمی‌دهد و مقدار مقصد حفظ می‌شود. عدد صحیح و اعشاری با هم سازگارند؛ آبجکت و آرایه هر دو JSON هستند. nullذخیره‌شده یک مقدار معتبر است و با نبود فایل فرق دارد.
نتیجه و خطاها
متغیر نتیجه اختیاری و JSON است؛ نامش باید با متغیر داده متفاوت باشد. نمونهٔ موفق:
{"success":true,"code":"ok","error":null,"found":true,"key":"progress","updatedAt":"2026-10-30T10:00:00.000Z","account":"user@example.com"}
در خطا، success برابر false و error توضیح قابل نمایش است. در not_found، مقدار found برابر false است؛ در خطاهایی که وجود داده معلوم نیست، found برابر null است. آدرس حساب بالا صرفاً نمونه است.
| کد | اقدام پیشنهادی |
|---|---|
not_found | داده‌ای برای این حساب و کلید نیست؛ حساب و کلید را بررسی کنید. |
cancelled | کاربر انتخاب حساب یا مجوز را لغو کرده؛ با انتخاب خودش دوباره اجرا کند. |
not_configured | شناسه OAuth، نام بسته و امضا را بررسی و خروجی جدید بسازید. |
authorization_required | اتصال یا مجوز نیاز به تجدید دارد؛ دوباره تلاش کنید. |
access_denied | دسترسی رد شده؛ فعال بودن API، مجوز و ظرفیت حساب را بررسی کنید. |
network_error | اینترنت را بررسی و دوباره اجرا کنید. |
rate_limited | درخواست‌ها زیادند؛ با فاصله تلاش کنید. |
busy | تا پایان عملیات ابری در حال اجرا صبر کنید. |
unsupported | از خروجی جدید اندروید استفاده کنید؛ پیش‌نمایش به Drive متصل نیست. |
variable_not_found | ابتدا متغیر مبدأ را بسازید. |
invalid_key | قالب و طول کلید را اصلاح کنید. |
invalid_variable / invalid_result_variable | نام مقصد یا نتیجه نامعتبر است یا تداخل دارد. |
invalid_value / invalid_data | مقدار قابل ذخیره نیست یا فایل خراب/ناسازگار است. |
type_mismatch | مقصدی با نوع سازگار انتخاب کنید. |
too_large | سقف فایل JSON به همراه اطلاعات قالب یک مگابایت است. |
invalid_response / operation_failed | عملیات تکمیل نشده؛ دوباره تلاش و اتصال را بررسی کنید. |
در عملکرد چندگانه، اگر مرحلهٔ بعد به نتیجه وابسته است، انتظار برای پایان را فعال کنید. برای اجرای مرحلهٔ بعد فقط در موفقیت، از «عملکرد پس از موفقیت» استفاده کنید.
محدودیت‌ها
- آخرین مقدار هر کلید نگهداری می‌شود؛ تاریخچهٔ قابل انتخاب و ادغام رکوردها وجود ندارد. ذخیرهٔ بعدی همان کلید، مقدار قبلی را جایگزین می‌کند. بازنویسی همزمان چند دستگاه را در طراحی اپ در نظر بگیرید.
- ذخیره و دریافت به اینترنت نیاز دارند. صف آفلاین و اجرای خودکار پس‌زمینه وجود ندارد؛ در حالت آفلاین موفقیت گزارش نمی‌شود.
- ذخیرهٔ مسیر فایل، خود تصویر، صوت یا فایل محلی را منتقل نمی‌کند.
- کاربر می‌تواند مجوز اپ یا دادهٔ خصوصی آن را از حساب گوگل حذف کند؛ در این صورت پشتیبان ممکن است از دسترس خارج شود.
- اعتبار خرید، اشتراک یا موجودی مالی سرور را از فایل پشتیبان تأیید نکنید.
منابع: دادهٔ مخصوص اپ در Drive، دسترسی‌های Drive.