Web APIs Bridge

1Web API Bridge چیست؟#

WebView در Android چند Web API مدرن را که Chrome دارد پشتیبانی نمی‌کند. اپلیکیشن ساخته‌شدهٔ شما این APIها را خودکار polyfill می‌کند تا وب‌سایت‌ها مثل Chrome کار کنند:

✅ Web Notifications (Notification API)
✅ Web Share (navigator.share)
✅ Clipboard (navigator.clipboard)
✅ window.close()
✅ پیوندهای target="_blank" و window.open()

نیازی به تنظیم نیست - این‌ها در هر اپلیکیشن ساخته‌شده خودکار کار می‌کنند.

2Web Notifications#

وب‌سایت‌هایی که از Notification.requestPermission() و new Notification() استفاده می‌کنند، اعلان‌های واقعی Android نشان می‌دهند.

• در Android 13 و بالاتر، کاربر پنجرهٔ مجوز سیستمی می‌بیند
• در Android 12 و پایین‌تر، اعلان‌ها به‌طور پیش‌فرض مجاز هستند
• زدن روی اعلان، اپلیکیشن را باز می‌کند
• گزینهٔ 'tag' اعلان‌های قبلی را جایگزین می‌کند (مطابق مشخصات وب)

// Your website JS — works the same as in Chrome:
Notification.requestPermission().then(function(result) {
  if (result === 'granted') {
    new Notification('Hello!', {
      body: 'This is a native Android notification',
      tag: 'my-notif'
    });
  }
});

3Web Share API#

navigator.share() برگهٔ اشتراک‌گذاری بومی Android را باز می‌کند تا کاربران محتوا را به WhatsApp، Telegram، ایمیل و غیره بفرستند.

• از title، text و url پشتیبانی می‌کند
• navigator.canShare() مقدار true برمی‌گرداند
• دقیقاً مثل پنجرهٔ اشتراک‌گذاری Chrome کار می‌کند

// Share content from your website:
navigator.share({
  title: 'Check this out',
  text: 'Amazing content!',
  url: 'https://example.com/page'
});

4Clipboard API#

navigator.clipboard.writeText() و readText() به کلیپ‌بورد بومی Android وصل شده‌اند.

• writeText() متن را در کلیپ‌بورد سیستم کپی می‌کند
• readText() از کلیپ‌بورد سیستم می‌خواند
• هر دو Promise برمی‌گردانند (مطابق مشخصات وب)

// Copy to clipboard:
await navigator.clipboard.writeText('Hello World');

// Read from clipboard:
const text = await navigator.clipboard.readText();

5window.close() و target="_blank"#

دو کمبود رایج WebView هم رفع شده است:

• window.close() - فعالیت اپلیکیشن را می‌بندد/تمام می‌کند (برای صفحه‌های بازگشت پرداخت/احراز هویت مفید است)
• پیوندهای target="_blank" - داخل WebView بارگذاری می‌شوند و بی‌صدا رها نمی‌شوند
• فراخوانی‌های window.open() - به همین شکل مدیریت می‌شوند

نیازی به تغییر وب‌سایت نیست - همین‌ها کار می‌کنند.

6تطبیق دامنه برای پیوندهای خارجی#

وقتی «External Links ← Open in Browser» تنظیم باشد، اپلیکیشن دامنه‌ها را هوشمندانه تطبیق می‌دهد:

• google.com و www.google.com یک دامنهٔ یکسان محسوب می‌شوند
• فقط دامنه‌های واقعاً متفاوت در Chrome باز می‌شوند
• تغییر مسیرها در همان سایت در WebView می‌مانند

این از مشکلی جلوگیری می‌کند که سایتی مثل google.com به www.google.com هدایت می‌شود و به‌اشتباه در Chrome باز می‌شود.

7پیوندهای UPI و اپلیکیشن‌های پرداخت (Razorpay، GPay، PhonePe، Paytm)#

هر پیوندی که scheme آن صفحهٔ وب نباشد، خودکار اپلیکیشن Android مربوطه را باز می‌کند - بدون تنظیم و بدون فهرست scheme برای پیکربندی:

• upi://pay - intent عمومی UPI (کاربر اپلیکیشن UPI خود را انتخاب می‌کند)
• paytmmp:// (Paytm)، phonepe://، tez:// (Google Pay)، gpay://
• tel:، mailto:، sms:، whatsapp://، tg://، intent://

این در هر جایی که صفحه می‌تواند به آن برود کار می‌کند:
✅ پیوند <a href="upi://pay?..."> که زده شود
✅ تغییر مسیر JS (window.location.href = 'upi://...')
✅ یک پنجرهٔ بازشو - window.open('paytmmp://...') - که Razorpay Checkout از این طریق به اپلیکیشن‌های UPI می‌رود

پس صفحه‌های checkout در Razorpay / Cashfree / PhonePe همان‌طور که هستند کار می‌کنند: مشتری یک گزینهٔ UPI را می‌زند، اپلیکیشن پرداخت باز می‌شود، تأیید می‌کند و وقتی برمی‌گردد، کنترل‌گر موفقیت صفحهٔ شما اجرا می‌شود. اگر هیچ اپلیکیشنی روی گوشی این scheme را پشتیبانی نکند، به‌جای صفحهٔ خطای خالی یک پیام کوتاه واضح می‌بیند.

⚠️ کالای دیجیتال را در اپلیکیشن Play Store می‌فروشید؟ Google برای آن‌ها Play Billing را الزامی می‌کند - به‌جای این از راهنمای IAP استفاده کنید. پرداخت UPI/کارت برای کالای فیزیکی، خدمات و اپلیکیشن‌هایی است که خارج از Play توزیع می‌شوند.

<!-- Simplest form — a plain UPI intent link. The user's phone
     shows every installed UPI app (GPay/PhonePe/Paytm/BHIM): -->
<a href="upi://pay?pa=merchant@bank&pn=MyStore&am=99.00&cu=INR&tn=Order%20123">
  Pay ₹99 via UPI
</a>

8مثال کامل - Razorpay Checkout با UPI، از ابتدا تا انتها#

یک مسیر کامل و قابل کپی با Razorpay Checkout. روی گوشی چه اتفاقی می‌افتد:

1. مشتری «Pay ₹499» را می‌زند ← Razorpay Checkout در صفحه باز می‌شود
2. مشتری UPI را انتخاب می‌کند ← اپلیکیشن UPI او خودکار باز می‌شود (همان انتقال paytmmp:// / phonepe:// که اپلیکیشن برایتان انجام می‌دهد)
3. مشتری در اپلیکیشن UPI تأیید می‌کند و برمی‌گردد - Android خودش اپلیکیشن شما را به جلو می‌آورد
4. تابع handler با شناسهٔ پرداخت اجرا می‌شود ← صفحهٔ موفقیت خود را نشان دهید
5. اگر لغو کنند dismiss اجرا می‌شود ← بگذارید دوباره امتحان کنند

rzp_test_XXXXXXXX را با کلید خودتان از dashboard.razorpay.com جایگزین کنید. ابتدا با یک کلید key_test آزمایش کنید - حالت آزمایشی Razorpay تأیید UPI را شبیه‌سازی می‌کند.

⚠️ برای یک فروشگاه واقعی، پیش از ارسال کالا پرداخت را در سمت سرور تأیید کنید (webhook در Razorpay یا Orders API + بررسی امضا) - handler سمت مرورگر به‌تنهایی قابل جعل است.

<!doctype html>
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://checkout.razorpay.com/v1/checkout.js"></script>

<h2>Premium Plan — ₹499</h2>
<button id="payBtn">Pay ₹499</button>
<p id="result"></p>

<script>
document.getElementById('payBtn').onclick = function () {
  var rzp = new Razorpay({
    key: 'rzp_test_XXXXXXXX',      // your Razorpay Key ID
    amount: 49900,                  // paise — ₹499.00
    currency: 'INR',
    name: 'My Store',
    description: 'Premium Plan',
    prefill: { contact: '', email: '' },
    theme: { color: '#2563eb' },

    // Fires after the customer returns from their UPI app
    handler: function (response) {
      document.getElementById('result').textContent =
        '✅ Paid! Payment ID: ' + response.razorpay_payment_id;
      // Real store: send response.razorpay_payment_id to your
      // server / webhook flow and verify before unlocking anything.
    },

    modal: {
      ondismiss: function () {
        document.getElementById('result').textContent =
          'Payment cancelled — tap Pay to try again.';
      }
    }
  });
  rzp.open();
};
</script>