الربط العميق

1ما هي الروابط العميقة؟#

تتيح الروابط العميقة لمصادر خارجية (المتصفحات والرسائل النصية والبريد الإلكتروني ووسائل التواصل والإشعارات الفورية ورموز QR) فتح تطبيقك مباشرة على صفحة محددة بدلًا من الصفحة الرئيسية.

يدعم تطبيقك نوعين، وليسا بنفس السهولة:

1. ⚡ مخطط مخصص (myapp://path) - يعمل فورًا دون أي إعداد. الأفضل للإشعارات الفورية ورموز QR.

1. 🌐 روابط https:// (https://mysite.com/page) - تحتاج إلى رفع ملف واحد إلى موقعك. بدونه يُبقي Android الرابط في المتصفح ولا يُفتح تطبيقك أبدًا. وهذا هو السبب الأشهر لعدم عمل الروابط العميقة.

كلاهما مشروح أدناه. إذا أردت فقط شيئًا يعمل اليوم، فاستخدم المخطط المخصص.

2كيف تعمل روابط المخطط المخصص#

عند النقر على رابط مخطط مخصص (مثل myapp://products/shoes)، يقوم التطبيق بما يلي:

1. يستقبل رابط المخطط المخصص
2. يحوّله تلقائيًا إلى رابط موقعك
3. يفتح WebView على الصفحة الصحيحة

✅ يُشتق المخطط من اسم تطبيقك (أحرف صغيرة، حروف فقط).

✅ مثال على التحويل:
myapp://products/shoes
← https://mysite.com/products/shoes

تُحفظ أجزاء المسار بعد المخطط وتُلحق بنطاق موقعك.

Custom scheme format:
  <appname>://<path>

Examples:
  myshop://cart
  → https://myshop.com/cart

  puma://in/en/help
  → https://in.puma.com/in/en/help

3روابط https:// - يجب وضع ملف واحد على موقعك#

هذا هو الجزء الذي يفوّته الناس، فاقرأه قبل الاختبار.

يضع AppMint نطاقك في التطبيق تلقائيًا. لكن Android لن يفتح تطبيقك من رابط https:// حتى يثبت موقعك أن التطبيق يخصّك. في Android 12 وما بعده، الرابط غير المُثبَت يفتح المتصفح فقط - دون نافذة ودون خيار. لهذا قد يبدو الرابط وكأنه «لا يفعل شيئًا».

الإثبات هو ملف صغير واحد. أنشأه لك AppMint بالفعل: بعد البناء، ابحث في التنزيلات عن assetlinks.json. يحتوي على اسم حزمتك وبصمة توقيع تطبيقك.

ارفعه إلى موقعك على هذا العنوان تمامًا (اسم المجلد يبدأ بنقطة):

https://yoursite.com/.well-known/assetlinks.json

Rules — all four must be true:
  1. Served over https (not http)
  2. Content-Type: application/json
  3. NO redirect (a redirect to www breaks it)
  4. Reachable publicly — no login, no Cloudflare challenge

Check it from any computer:
  curl -i https://yoursite.com/.well-known/assetlinks.json

4تنشر على Google Play؟ استخدم بصمة Play#

يعيد Google Play توقيع تطبيقك بمفتاحه الخاص. لذلك فإن البصمة داخل assetlinks.json الذي أنشأه AppMint - وهي مفتاحك المحلي - لن تطابق ما يثبّته المستخدمون فعليًا من Play.

إذا كنت تنشر على Play، فاستبدل البصمة:

1. Play Console ← تطبيقك ← Test and release ← Setup ← App integrity
2. انسخ SHA-256 من 'App signing key certificate'
3. ضع هذه القيمة في assetlinks.json وأعد رفعه

يمكنك إدراج البصمتين معًا في الملف نفسه - المحلية لملفات APK التي تشاركها مباشرة، وبصمة Play لعمليات التثبيت من Play. بهذا يعمل كلاهما.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.yourapp.name",
    "sha256_cert_fingerprints": [
      "AA:BB:...",   // your local key (direct APK)
      "11:22:..."    // Play App Signing key
    ]
  }
}]

5تحقق مما إذا قبله Android#

بعد رفع الملف، أعد تثبيت التطبيق (Android يتحقق وقت التثبيت فقط، وقد يستغرق ذلك دقيقة).

الأمر أدناه يخبرك بالحقيقة. ابحث عن نطاقك مع كلمة 'verified'. إذا ظهرت 'legacy_failure' أو كان النطاق مفقودًا، فالملف لا يُقرأ بشكل صحيح - ارجع وتحقق من القواعد الأربع.

# Does Android consider your domain verified?
adb shell pm get-app-links com.yourapp.name

# Force a re-check without reinstalling (Android 12+):
adb shell pm verify-app-links --re-verify com.yourapp.name

# Google's own checker (open in a browser):
https://digitalassetlinks.googleapis.com/v1/statements:list?
  source.web.site=https://yoursite.com&
  relation=delegate_permission/common.handle_all_urls

6لماذا يفشل عادةً#

بحسب مدى تكرار كل سبب:

1. الملف غير مرفوع، أو في مسار خاطئ. يجب أن يكون /.well-known/assetlinks.json - مع النقطة.

1. www مقابل بدون www. يعامل Android الرابطين https://example.com وhttps://www.example.com كنطاقين مختلفين. يسجّل AppMint المضيف نفسه الذي أدخلته في رابط موقعك. إذا استخدمت كليهما، فضع الملف على كليهما، وأخبرنا بالمضيف الذي أدخلته.

1. إعادة توجيه. تعيد كثير من الاستضافات توجيه النطاق الأساسي إلى www. وهذا يكسر التحقق حتى لو كان الملف يُحمَّل في المتصفح.

1. نُشر على Play لكن مع استخدام البصمة المحلية - راجع الخطوة السابقة.

1. لم يُعَد التثبيت بعد الرفع. Android يتحقق وقت التثبيت.

روابط المخطط المخصص (myapp://...) لا تحتاج إلى أي من هذا وتعمل دائمًا - استخدمها للإشعارات الفورية ورموز QR إن أردت شيئًا يعمل اليوم.

7اختبار الروابط العميقة عبر ADB#

اختبر روابطك العميقة من حاسوب متصل عبر تصحيح USB:

1. فعّل تصحيح USB على هاتفك
2. وصّل الهاتف عبر USB
3. نفّذ الأوامر أدناه.

⚠️ مهم: قد يفتح الأمر 'am start' مع رابط https تطبيقك حتى لو فشل التحقق، لأنك تسلّم الرابط مباشرة إلى Android. وهو لا يثبت أن نقرة حقيقية في Gmail أو Chrome ستعمل. فقط 'pm get-app-links' (الخطوة السابقة) يخبرك بذلك. استخدم am start لفحص توجيه صفحاتك، لا إعداد نطاقك.

# Test custom scheme:
adb shell am start -a android.intent.action.VIEW \
  -d "myapp://some/page"

# Test website URL:
adb shell am start -a android.intent.action.VIEW \
  -d "https://mysite.com/some/page"

# Verify which app handles it:
adb shell cmd package resolve-activity --brief \
  -a android.intent.action.VIEW \
  -d "myapp://some/page"

8الروابط العميقة في الإشعارات الفورية#

عند إرسال إشعار فوري عبر OneSignal، الصق أي رابط عميق في حقل 'Launch URL'. سيفتح التطبيق وينتقل مباشرة إلى تلك الصفحة.

كلا نوعي الروابط يعملان:
✅ https://mysite.com/flash-sale
✅ myapp://flash-sale

OneSignal Dashboard → New Push:

Launch URL: https://mysite.com/flash-sale
  OR
Launch URL: myapp://flash-sale

Both will open the app on the sale page.

9مهم: سلوك التشغيل الدافئ#

إذا كان تطبيقك يعمل بالفعل في الخلفية عند تفعيل رابط عميق، يسلّم Android الرابط مباشرة دون إعادة تشغيل التطبيق - وهذا ما يسمى «التشغيل الدافئ».

✅ يتولى تطبيقك هذا تلقائيًا. سينتقل WebView إلى الصفحة الجديدة حتى لو كان التطبيق مفتوحًا بالفعل.

⚠️ إذا كانت الروابط العميقة تفتح الصفحة الرئيسية فقط، فتحقق من أن:

• رابط موقعك في الإعدادات يطابق النطاق في الرابط العميق
• المسار في رابط المخطط المخصص صحيح

⚠️ إذا لم تفتح روابط https:// التطبيق إطلاقًا، فهذه ليست مشكلة تشغيل دافئ - بل هي خطوة assetlinks.json أعلاه. عمل روابط المخطط المخصص بينما لا تفعل روابط https شيئًا هو العلامة الكلاسيكية.

Warm launch works automatically.
No extra setup needed.