جسر واجهات الويب

1ما هي جسور Web API؟#

لا يدعم Android WebView عدة واجهات ويب حديثة يدعمها Chrome. يضيف تطبيقك المولَّد تلقائيًا بدائل لهذه الواجهات لتعمل المواقع تمامًا كما في 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() يقرأ من حافظة النظام
• كلاهما يعيد Promises (وفق مواصفات الويب)

// 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)#

أي رابط ليس مخططه صفحة ويب يفتح تلقائيًا تطبيق Android الذي يملكه - دون إعداد ودون قائمة مخططات لتهيئتها:

• upi://pay - نية 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

لذا تعمل صفحات دفع Razorpay / Cashfree / PhonePe كما هي: يضغط العميل خيار UPI، فيفتح تطبيق الدفع، ويوافق، ثم يعمل معالج النجاح في صفحتك عند عودته. وإذا لم يوجد على الهاتف تطبيق يتعامل مع هذا المخطط، يرى المستخدم رسالة toast واضحة بدل صفحة خطأ فارغة.

⚠️ هل تبيع سلعًا رقمية في تطبيق على 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. تُستدعى دالة المعالج مع معرّف دفع ← اعرض شاشة النجاح
5. يُطلق dismiss إذا ألغى المستخدم ← دعه يعيد المحاولة

استبدل rzp_test_XXXXXXXX بمفتاحك من dashboard.razorpay.com. اختبر بمفتاح key_test أولًا - يحاكي وضع الاختبار في Razorpay موافقة UPI.

⚠️ في متجر حقيقي، أكّد الدفع من جهة الخادم (Razorpay webhook أو Orders API مع التحقق من التوقيع) قبل شحن البضائع - فالمعالج في المتصفح وحده يمكن تزويره.

<!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>