Skip to main content
Deep linking allows your NativePHP Mobile app to open from URLs, whether from web browsers, other apps, or NFC tags. Configure custom URL schemes and associate verified HTTPS domains.

​
Configuration

Deep links are configured in config/nativephp.php: 
'deeplink_scheme' => env('NATIVEPHP_DEEPLINK_SCHEME'),
'deeplink_host' => env('NATIVEPHP_DEEPLINK_HOST'),
Set these values in your .env file: 
NATIVEPHP_DEEPLINK_SCHEME=myapp
NATIVEPHP_DEEPLINK_HOST=example.com

​
Applying Changes

After configuring deep links, rebuild the native configuration: 
php artisan native:install --force
php artisan native:run
URL scheme deep links use a custom protocol to open your app: 
myapp://path/to/page?param=value

​
Choosing a URL Scheme

Your URL scheme should be:
  • Unique: Avoid conflicts with other apps
  • Lowercase: Use only lowercase letters
  • Memorable: Easy for users to recognize
  • Branded: Related to your app or company name
Good examples:
  • nativephp://
  • mystore://
  • acmecorp://
Avoid:
  • Common words (app://, open://)
  • Generic terms (link://, mobile://)
  • Existing schemes (http://, mailto://)

​
Configuring URL Scheme

# .env
NATIVEPHP_DEEPLINK_SCHEME=myapp
This allows URLs like:
  • myapp://home
  • myapp://products/123
  • myapp://settings?tab=account

​
Testing URL Schemes

iOS: 
xcrun simctl openurl booted myapp://home
Android: 
adb shell am start -a android.intent.action.VIEW -d "myapp://home"
From a web page: 
<a href="myapp://products/123">Open in App</a>
HTTPS deep links allow regular web URLs to open your app when tapped: 
https://example.com/products/123
If the app is installed, the link opens the app. If not, it opens in the browser. 
# .env
NATIVEPHP_DEEPLINK_HOST=example.com
This allows URLs like:
  • https://example.com/home
  • https://example.com/products/123
  • https://example.com/settings?tab=account

​
Platform Requirements

iOS Universal Links require hosting an apple-app-site-association file on your domain: File location: 
https://example.com/.well-known/apple-app-site-association
File content: 
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAM_ID.com.example.app",
        "paths": ["*"]
      }
    ]
  }
}
Replace:
  • TEAM_ID with your Apple Developer Team ID
  • com.example.app with your app’s bundle identifier
  • ["*"] with specific paths if you don’t want all URLs to open the app
Requirements:
  • File must be served over HTTPS
  • Content-Type must be application/json
  • No redirects allowed
  • File must be accessible without authentication
Android App Links require hosting a assetlinks.json file: File location: 
https://example.com/.well-known/assetlinks.json
File content: 
[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [
        "YOUR_CERTIFICATE_FINGERPRINT"
      ]
    }
  }
]
Replace:
  • com.example.app with your app’s package name
  • YOUR_CERTIFICATE_FINGERPRINT with your app signing certificate’s SHA-256 fingerprint
Getting your certificate fingerprint: 
keytool -list -v -keystore my-release-key.keystore
Requirements:
  • File must be served over HTTPS
  • Content-Type must be application/json
  • File must be accessible without authentication
HTTPS deep links only work when both the domain verification file is correctly configured AND the app is installed from the App Store/Play Store or signed with a release certificate.
When a deep link opens your app, NativePHP dispatches it as a Laravel route. Handle deep links in your routes/web.php or routes/native.php: 
// routes/web.php

use Illuminate\Support\Facades\Route;

// Handle: myapp://home or https://example.com/home
Route::get('/home', function () {
    return view('home');
});

// Handle: myapp://products/123 or https://example.com/products/123
Route::get('/products/{id}', function ($id) {
    return view('product', ['id' => $id]);
});

// Handle: myapp://settings?tab=account
Route::get('/settings', function (Request $request) {
    $tab = $request->query('tab', 'general');
    return view('settings', ['tab' => $tab]);
});
Deep links are handled through Laravel’s routing system. When a user taps a deep link, your app opens and Laravel routes the request to the appropriate controller or page. Define routes that match your deep link structure: 
// routes/web.php

Route::get('/products/{id}', function ($id) {
    return view('product', ['id' => $id]);
})->name('product');

Route::get('/checkout', function () {
    return view('checkout');
})->name('checkout');
Handle deep link parameters in Livewire components: 
use Livewire\Component;

class ProductPage extends Component
{
    public $productId;

    public function mount($id)
    {
        $this->productId = $id;
        // Load product details based on the ID from the deep link
    }

    public function render()
    {
        return view('livewire.product-page');
    }
}
Redirect to a specific page when a deep link is received: 
// routes/web.php

Route::get('/products/{id}', function ($id) {
    // Redirect to the product page
    return redirect()->route('product', ['id' => $id]);
});

​
NFC Tag Integration

NFC functionality is not currently provided as a built-in facade in NativePHP Mobile. You can implement NFC support using custom plugins.
NFC tags can store URLs that, when tapped, open your app through deep links.
1

User taps NFC tag

Device reads the URL from the NFC tag (e.g., https://example.com/products/123)
2

System checks for app association

Operating system checks if your app is associated with the domain
3

App opens

Your app opens and Laravel routes the request to /products/123
4

Route handler processes request

Your route or controller loads the product and displays it

​
Setting Up NFC Tags

To enable NFC deep links:
  1. Write your app’s deep link URL to an NFC tag using an NFC writing app
  2. Ensure the URL matches your configured deeplink_host
  3. Configure proper domain verification files (see HTTPS Deep Links section above)
When users tap the NFC tag, the URL will open your app if it’s installed, or open in a browser otherwise.

​
NFC Tag Best Practices

HTTPS URLs work both when the app is installed and when it’s not (falling back to browser).
NFC tags have limited storage. Use short, clean URLs.
iOS and Android handle NFC differently. Test your tags on both platforms.
Ensure the URL works in a browser for users who don’t have the app installed.

​
Parameter Extraction

Extract parameters from deep link URLs: 
// routes/web.php

Route::get('/share/{type}/{id}', function ($type, $id) {
    // Handle: myapp://share/product/123
    // Handle: myapp://share/post/456
    return view('share', ['type' => $type, 'id' => $id]);
});

​
Query Parameters

Handle query parameters in deep links: 
Route::get('/search', function (Request $request) {
    // Handle: myapp://search?q=laptop&category=electronics
    $query = $request->query('q');
    $category = $request->query('category');
    
    return view('search', [
        'query' => $query,
        'category' => $category,
    ]);
});

​
Authentication Gates

Protect deep link routes with authentication: 
Route::get('/account/orders/{id}', function ($id) {
    // Handle: myapp://account/orders/123
    // Redirects to login if not authenticated
    return view('order', ['id' => $id]);
})->middleware('auth');
Generate deep links programmatically: 
// Generate a URL scheme deep link
$scheme = config('nativephp.deeplink_scheme');
$deepLink = "{$scheme}://products/123";

// Generate an HTTPS deep link
$host = config('nativephp.deeplink_host');
$httpsLink = "https://{$host}/products/123";

// Or use Laravel's url() helper
$httpsLink = url('/products/123');
Share deep links via the native share sheet: 
use Native\Mobile\Facades\Share;

// Share a deep link
$host = config('nativephp.deeplink_host');
Share::share(
    'Check out this product!',
    '',
    "https://{$host}/products/123"
);

​
Testing in Development

iOS Simulator: 
# Test URL scheme
xcrun simctl openurl booted myapp://home

# Test HTTPS (won't open app in simulator without proper setup)
xcrun simctl openurl booted https://example.com/home
Android Emulator: 
# Test URL scheme
adb shell am start -a android.intent.action.VIEW -d "myapp://home"

# Test HTTPS
adb shell am start -a android.intent.action.VIEW -d "https://example.com/home"

​
Testing on Physical Devices

  1. Send yourself an email or message with the deep link
  2. Tap the link in the email/message
  3. Verify the app opens and handles the link correctly
HTTPS deep links require:
  • App installed from App Store/Play Store (or signed with release certificate)
  • Domain verification files properly configured
  • Domain accessible over HTTPS
Verify iOS Universal Links: 
# Check if your domain is configured correctly
curl https://example.com/.well-known/apple-app-site-association
Verify Android App Links: 
# Check if your domain is configured correctly
curl https://example.com/.well-known/assetlinks.json

​
Troubleshooting

  1. Verify NATIVEPHP_DEEPLINK_SCHEME is set in .env
  2. Run php artisan native:install --force
  3. Rebuild and reinstall the app
  4. Test with the correct URL format: scheme://path
  1. Verify domain verification files are accessible:
    • https://example.com/.well-known/apple-app-site-association
    • https://example.com/.well-known/assetlinks.json
  2. Ensure files are served over HTTPS with no redirects
  3. Verify app is signed with release certificate or installed from store
  4. Check Team ID and bundle identifier (iOS) or package name and certificate fingerprint (Android)

​
NFC tags not opening app

  1. Ensure NFC is enabled on the device
  2. Verify the NFC tag contains a valid URL that matches your configured domain
  3. Test the URL in a browser first to ensure it works
  4. Verify domain verification files are properly configured
  1. Verify routes are defined in routes/web.php
  2. Check that route parameters match the URL structure
  3. Test the route directly in your app first
  4. Clear Laravel route cache: php artisan route:clear

​
Best Practices

Configure both for maximum compatibility. URL schemes work everywhere, HTTPS deep links provide a better user experience.
Use the same URL structure for web, deep links, and NFC tags.
Always validate and provide defaults for deep link parameters.
HTTPS deep links only work correctly on physical devices with proper signing.
Ensure your HTTPS deep link URLs work in a browser for users without the app.

​
Next Steps

Share

Share deep links via the native share sheet

Browser

Open URLs and handle OAuth flows

Build docs developers (and LLMs) love

Get started for freeTalk to us