پرش به مطلب اصلی

ثبت یادآوری

این عملکرد یک اعلان را برای چند دقیقه بعد یا تاریخ و ساعت مشخصی در آینده ثبت می‌کند. در Android و iOS، سیستم‌عامل مسئول نمایش یادآوری است و باز بودن اپ لازم نیست؛ مجوزها و محدودیت‌های دستگاه بر نمایش آن اثر دارند.

برای استفاده از زمان مشخص و بازیابی جدید یادآورها در اپ‌های قبلی، خروجی جدید بسازید.

تنظیمات​

  • کلید یکتا: نام یکتای یادآوری. اگر یادآوری دیگری با همان کلید ثبت شود، جایگزین یادآوری قبلی می‌شود. برای لغو یادآوری نیز به همین کلید نیاز دارید.
  • عنوان و متن: محتوای اعلانی که در زمان یادآوری نمایش داده می‌شود.
  • روش تعیین زمان: «چند دقیقه بعد» یا «تاریخ و ساعت مشخص».
  • زمان از متغیر: در روش «چند دقیقه بعد»، تعداد دقیقه از یک متغیر خوانده می‌شود.
  • چند دقیقه بعد: فاصله تا اولین اجرا، بر حسب دقیقه؛ حداقل 1 و فقط در روش تأخیر.
  • متغیر زمان: متغیر دارای تعداد دقیقه، در صورت فعال بودن «زمان از متغیر».
  • تاریخ و ساعت مشخص: موعد اولیه با قالبی که در بخش بعد آمده است.
  • زمان مشخص از متغیر: موعد به جای مقدار ثابت، از «متغیر زمان مشخص» خوانده می‌شود.
  • متغیر زمان مشخص: متغیر دارای زمان یونیکس میلی‌ثانیه یا متن تاریخ میلادی با منطقه زمانی.
  • تکرار: یکی از حالت‌های «بدون تکرار»، «روزانه» یا «هفتگی».
  • زمان‌بندی دقیق: درخواست ثبت دقیق در موعد تعیین‌شده؛ در Android به مجوز لازم نیاز دارد و با رد مجوز، یادآوری ثبت نمی‌شود. در حالت غیرفعال، سیستم‌عامل ممکن است برای صرفه‌جویی در باتری اعلان را با تأخیر نمایش دهد.
  • صفحه بعد از لمس: صفحه‌ای که با لمس اعلان باز می‌شود.
  • داده همراه: مقدار متنی دلخواه که پس از لمس اعلان از sys.notification.data قابل خواندن است.
استفاده از متغیر

عنوان، متن، کلید و داده همراه می‌توانند شامل متغیر با الگوی {{myvar}} باشند.

تاریخ و ساعت مشخص​

روش تعیین زمان را تاریخ و ساعت مشخص بگذارید. مقدار باید یکی از این دو قالب باشد:

  • یونیکس میلی‌ثانیه: تعداد میلی‌ثانیه از ابتدای زمان یونیکس؛ مقدار ثانیه‌ای را مستقیم وارد نکنید.
  • تاریخ میلادی ISO-8601 با منطقه زمانی: مانند 2026-12-01T15:30:00+03:30 برای ساعت ۱۵:۳۰ با آفست +03:30، یا 2026-12-01T12:00:00Z برای زمان UTC.

این‌ها فقط نمونه قالب‌اند؛ زمان واقعی موردنظر را وارد کنید. تاریخ شمسی، متن‌هایی مانند «فردا ساعت ۹» و تاریخ بدون Z یا آفست پذیرفته نمی‌شوند. موعد باید در آینده باشد؛ اگر هنگام گرفتن مجوز از موعد عبور کردید، زمان تازه‌ای انتخاب کنید.

برای خواندن موعد از داده‌های اپ یا پاسخ سرویس، زمان مشخص از متغیر را فعال کنید و متغیر حاوی یکی از قالب‌های بالا را انتخاب کنید. حداقل یک دقیقه مربوط به روش «چند دقیقه بعد» است؛ در روش زمان مشخص، شرط اصلی معتبر بودن موعد و قرار داشتن آن در آینده است.

رفتار حالت‌های تکرار​

تکرارنتیجه
بدون تکراراعلان فقط یک بار در موعد اولیه ثبت می‌شود.
روزانهاز موعد اولیه، هر روز در همان ساعت تکرار می‌شود.
هفتگیاز موعد اولیه، هر هفته در همان روز و ساعت تکرار می‌شود.

منطقه زمانی دستگاه در زمان ثبت برای تکرار نگه داشته می‌شود. تغییر منطقه زمانی دستگاه بعد از ثبت، منطقه زمانی این یادآوری را عوض نمی‌کند؛ برای انتخاب منطقه زمانی تازه، یادآوری را با همان کلید دوباره ثبت کنید.

در iOS، موعد آغاز یک تکرار باید نزدیک‌ترین نوبت روزانه یا هفتگی باشد. مثلاً تکرار روزانه‌ای که ساعتش فردا می‌رسد، نمی‌تواند از چند هفته بعد شروع شود؛ چنین درخواست‌هایی ناموفق می‌شوند.

متغیرهای نتیجه​

متغیرتوضیح
sys.notification.successآیا ثبت یادآوری موفق بود
sys.notification.errorمتن خطا در صورت ناموفق بودن
sys.notification.idشناسه عددی ساخته‌شده از کلید
sys.notification.keyکلید همین یادآوری
sys.notification.remindersفهرست یادآوری‌های نگه‌داری‌شده، همراه وضعیت ثبت و مجوزهای لازم

متغیر sys.notification.reminders یک آرایه است و می‌توانید آن را به‌عنوان منبع داده ویجت لیست پویا استفاده کنید تا یادآوری‌های ثبت‌شده کاربر را نمایش دهید. ساختار هر آیتم در متغیرهای سیستمی توضیح داده شده است.

وجود آیتم در فهرست به‌تنهایی نشان نمی‌دهد که آماده نمایش است. برای نمایش وضعیت، status، registered و nextAt همان آیتم را بخوانید؛ مثلاً exactPermissionRequired به معنی نیاز به مجوز زمان‌بندی دقیق است. نتیجه موفق ثبت نیز تضمین نمی‌کند که کاربر بعداً مجوز را لغو نکند.

نمونه کاربرد​

برای ساخت یک یادآور دارو، مقدار دقیقه را از یک فیلد عددی در متغیر reminderMinutes ذخیره کنید، سپس این عملکرد را با کلید medicine، تکرار «روزانه» و گزینه «زمان از متغیر» تنظیم کنید. برای غیرفعال کردن یادآور، عملکرد لغو یادآوری را با همان کلید medicine اجرا کنید.

بازیابی یادآورها​

یادآورها در دستگاه نگه‌داری می‌شوند. اپ هنگام اجرا، وضعیت آن‌ها را با درخواست‌های ثبت‌شده در سیستم‌عامل تطبیق می‌دهد. در Android، بازیابی پس از راه‌اندازی مجدد دستگاه و به‌روزرسانی اپ نیز انجام می‌شود؛ ثبت دوباره به مجوز اعلان و، در حالت دقیق، مجوز زمان‌بندی دقیق نیاز دارد.

در بازیابی، یادآوری یک‌باره‌ای که موعدش گذشته دوباره ثبت نمی‌شود و تکرارهای روزانه یا هفتگی به نوبت آینده منتقل می‌شوند. اگر مجوز لازم را برگردانده‌اید، اپ را باز کنید و وضعیت یادآورها را بررسی کنید.

نکات و محدودیت‌ها​

  • این قابلیت در نسخه فعلی فقط روی Android و iOS کار می‌کند.
  • در روش «چند دقیقه بعد»، کمترین فاصله مجاز یک دقیقه است.
  • بدون مجوز اعلان، ثبت موفق نمی‌شود. «زمان‌بندی دقیق» در Android نیز بدون مجوز مربوط ثبت نمی‌شود و خودکار به حالت غیردقیق تغییر نمی‌کند.
  • در iOS حداکثر ۶۴ یادآوری هم‌زمان قابل ثبت است؛ ثبت مورد تازه پس از پر شدن ظرفیت ناموفق می‌شود.
  • اگر کاربر اپ را حذف کند یا اطلاعات آن را پاک کند، یادآوری‌های ثبت‌شده نیز حذف می‌شوند.
  • در شبیه‌ساز، اعلان واقعی ثبت نمی‌شود؛ یک پیام کوتاه نمایش داده می‌شود و آیتم در فهرست یادآوری‌ها با status: simulated و registered: false می‌آید. این آیتم‌ها در داده‌های محلی پیش‌نمایش نگه‌داری می‌شوند؛ برای پاک کردنشان از عملکرد لغو یادآوری استفاده کنید.

عملکردهای مرتبط​