پیوند عمیق

1پیوند عمیق چیست؟#

پیوند عمیق به منابع بیرونی (مرورگرها، پیامک، ایمیل، شبکه‌های اجتماعی، اعلان‌های فوری، کدهای QR) اجازه می‌دهد اپلیکیشن شما را مستقیماً روی یک صفحه مشخص باز کنند، نه صفحه اصلی.

اپلیکیشن شما از دو نوع پشتیبانی می‌کند و آسانی آن‌ها یکسان نیست:

1. ⚡ طرح سفارشی (myapp://path) - فوراً کار می‌کند و نیازی به راه‌اندازی ندارد. بهترین گزینه برای اعلان‌های فوری و کدهای QR.

1. 🌐 پیوندهای https:// (https://mysite.com/page) - به بارگذاری یک فایل روی وب‌سایت شما نیاز دارد. بدون آن اندروید پیوند را در مرورگر نگه می‌دارد و اپلیکیشن شما هرگز باز نمی‌شود. این رایج‌ترین دلیل «کار نکردن» پیوندهای عمیق است.

هر دو در ادامه پوشش داده شده‌اند. اگر فقط امروز چیزی کارآمد می‌خواهید، از طرح سفارشی استفاده کنید.

2نشانی‌های طرح سفارشی چطور کار می‌کنند#

وقتی روی یک پیوند طرح سفارشی زده می‌شود (مثلاً myapp://products/shoes)، اپلیکیشن:

1. نشانی طرح سفارشی را دریافت می‌کند
2. آن را خودکار به نشانی وب‌سایت شما نگاشت می‌کند
3. WebView را روی صفحه درست باز می‌کند

✅ طرح (scheme) از نام اپلیکیشن شما ساخته می‌شود (حروف کوچک، فقط حروف).

✅ نمونه نگاشت:
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 دامنه شما را خودکار در اپلیکیشن قرار می‌دهد. اما اندروید تا وقتی وب‌سایت شما ثابت نکند اپلیکیشن متعلق به شماست، اپلیکیشن را از پیوند https:// باز نمی‌کند. در اندروید ۱۲ و جدیدتر، پیوند اثبات‌نشده فقط مرورگر را باز می‌کند - بدون پنجره و بدون انتخاب. برای همین است که یک پیوند ممکن است «هیچ کاری نمی‌کند».

گواه آن یک فایل کوچک است. AppMint قبلاً آن را برای شما ساخته است: بعد از ساخت، در پوشه Downloads دنبال 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بررسی کنید آیا اندروید آن را پذیرفته است#

بعد از بارگذاری فایل، اپلیکیشن را دوباره نصب کنید (اندروید فقط هنگام نصب بررسی می‌کند و ممکن است یک دقیقه طول بکشد).

دستور زیر حقیقت را می‌گوید. دامنه خود را با عبارت «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. اندروید نشانی‌های https://example.com و https://www.example.com را دو دامنه متفاوت می‌داند. AppMint دقیقاً همان میزبانی را ثبت می‌کند که در نشانی وب‌سایت شما آمده است. اگر از هر دو استفاده می‌کنید، فایل را روی هر دو بگذارید و به ما بگویید کدام میزبان را وارد کرده‌اید.

1. یک تغییر مسیر. بسیاری از میزبان‌ها دامنه اصلی را به www هدایت می‌کنند. این کار تأیید را خراب می‌کند، حتی اگر فایل در مرورگر بارگذاری شود.

1. در Play منتشر شده اما از اثر انگشت محلی استفاده شده - مرحله قبل را ببینید.

1. بعد از بارگذاری دوباره نصب نشده است. اندروید هنگام نصب بررسی می‌کند.

پیوندهای طرح سفارشی (myapp://...) به هیچ‌کدام از این‌ها نیاز ندارند و همیشه کار می‌کنند - اگر امروز چیزی کارآمد می‌خواهید، از آن‌ها برای اعلان‌های فوری و کدهای QR استفاده کنید.

7آزمایش پیوندهای عمیق با ADB#

پیوندهای عمیق خود را از یک رایانه متصل با اشکال‌زدایی USB آزمایش کنید:

1. اشکال‌زدایی USB را روی گوشی خود فعال کنید
2. با USB وصل کنید
3. دستورهای زیر را اجرا کنید.

⚠️ مهم: «am start» با پیوند https می‌تواند اپلیکیشن شما را حتی وقتی تأیید ناموفق بوده باز کند، چون پیوند را مستقیم به اندروید می‌دهید. این ثابت نمی‌کند که یک ضربه واقعی در 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مهم: رفتار راه‌اندازی گرم#

اگر وقتی پیوند عمیق فعال می‌شود اپلیکیشن شما از قبل در پس‌زمینه در حال اجراست، اندروید پیوند را مستقیم و بدون راه‌اندازی مجدد اپلیکیشن تحویل می‌دهد - به این «راه‌اندازی گرم» می‌گویند.

✅ اپلیکیشن شما این را خودکار مدیریت می‌کند. WebView حتی وقتی اپلیکیشن از قبل باز است به صفحه جدید می‌رود.

⚠️ اگر پیوندهای عمیق فقط صفحه اصلی را باز می‌کنند، این موارد را بررسی کنید:

• نشانی وب‌سایت شما در پیکربندی با دامنه پیوند عمیق یکی است
• مسیر در نشانی طرح سفارشی درست است

⚠️ اگر پیوندهای https:// اصلاً اپلیکیشن را باز نمی‌کنند، این مشکل راه‌اندازی گرم نیست - مربوط به مرحله assetlinks.json بالاست. کار کردن پیوندهای طرح سفارشی در حالی که پیوندهای https هیچ کاری نمی‌کنند، نشانه کلاسیک آن است.

Warm launch works automatically.
No extra setup needed.