Is your web platform preventing you from hosting essential files for app linking, such as the Apple App Site Association (AASA) or Android Digital Asset Links (assetlinks.json)? If so, Cloudflare Workers offer a simple solution to this common problem.

Below, we’ll explain how you can leverage Cloudflare Workers (via the Cloudflare dashboard) to serve your Apple App Site Association (AASA) file and Digital Asset Links (assetlinks.json) file.

(This technique is especially useful if you own your domain but use a web platform that does not allow you to host these files directly.)

Let’s get started.

When to use Cloudflare Workers

If your web platform doesn't let you place files at the required paths for iOS and Android app linking, Cloudflare Workers can help. 

With this setup, Cloudflare intercepts requests to those specific paths (like /apple-app-site-association and /.well-known/assetlinks.json) and serves the necessary JSON files directly from its edge network. 

Meanwhile, all other requests continue to be routed to your website as usual.

Step 1: Sign up for Cloudflare and set up your domain

1. Sign up for an account.
   Go to Cloudflare's sign-up page and create a free account.
2. Add your domain.
   
   • Log in to the Cloudflare dashboard.
   • Click "Add a Site" and enter your domain name.
   • Follow the guided process to update your DNS records (typically by changing your nameservers).

Step 2: Create a worker using the Cloudflare dashboard

1. Access Workers: From the Cloudflare dashboard, select "Workers" in the menu.
2. Create a new Worker: Click "Create a Worker". This will open the online editor where you can write your script.

Step 3: Insert and deploy Worker code

Paste the following code into the Cloudflare Workers editor: 

// JSON data for the Apple App Site Association file
const aasaData = {
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.co.median.example",
      "paths": ["*"]
    }]
  }
};

// JSON data for the Android Digital Asset Links file
const assetlinksData = [
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "co.median.android.padzoa",
      "sha256_cert_fingerprints": [
        "ED:30:0F:A9:AB:9D:00:34:9D:48:B0:91:69:83:D7:C9:FE:0A:95:FE:F2:E0:38:25:C9:97:37:D8:F3:16:0B:E0"
      ]
    }
  }
];

// Worker event listener that routes requests
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request));
});

async function handleRequest(request) {
  const url = new URL(request.url);

  // Serve the Apple App Site Association file
  if (url.pathname === '/apple-app-site-association') {
    return new Response(JSON.stringify(aasaData, null, 2), {
      headers: { 'Content-Type': 'application/json' }
    });
  }

  // Serve the assetlinks.json file
  if (url.pathname === '/.well-known/assetlinks.json') {
    return new Response(JSON.stringify(assetlinksData, null, 2), {
      headers: { 'Content-Type': 'application/json' }
    });
  }

  // Return a 404 response for any other paths
  return new Response('Not found', { status: 404 });
}

Explanation of the code

• Data definition: The AASA and assetlinks JSON objects are defined at the top as aasaData and assetlinksData. This separation allows you to update the JSON content without modifying the main logic.
• Event listener: The script listens for incoming fetch events and passes the request to the handleRequest function.
• Routing logic: The handleRequest function checks the request URL:
  
  • If the pathname is /apple-app-site-association, it returns the AASA JSON.
  • If the pathname is /.well-known/assetlinks.json, it returns the assetlinks JSON.
  • All other requests receive a 404 response.

3. Configure the Worker for your app: Replace the appID, package_name and sha256_cert_fingerprints with the configuration of your mobile app. 
4. Deploy the Worker: Click "Save and Deploy" in the Cloudflare Workers editor. Under the "Triggers" tab, add routes to ensure your Worker responds for the following paths:
   
   • yourdomain.com/apple-app-site-association
   • yourdomain.com/.well-known/assetlinks.json

Want to know how it all works?

Get hands-on with Median’s comprehensive documentation, and build your app with ease.

View Documentation

Step 4: Testing your endpoints

After deploying your Worker, use your browser to verify that the necessary endpoints are working correctly:

1. Check the special endpoints: 
   
   • Open your browser and navigate to https://yourdomain.com/apple-app-site-association. You should see the JSON content for the AASA file.
   • Then, visit https://yourdomain.com/.well-known/assetlinks.json to confirm that the assetlinks JSON is served correctly.
2. Verify the homepage: Finally, navigate to your website’s homepage (e.g., https://yourdomain.com) to ensure that it continues to load as expected and that the Worker is only intercepting requests for the specified paths.

Step 5: Validate your domain using Median’s Deep Linking Validator

After confirming that your endpoints and homepage work correctly, validate your deep linking setup to ensure both iOS and Android configurations are recognized.

1. Visit the Validator: Open your browser and go to Median’s Deep Linking Validator.
2. Enter your domain: Input your domain (e.g., https://yourdomain.com).
3. Run the validation: The tool will test that your AASA and assetlinks files are being served correctly. Review the results for any errors or issues.
4. Address any issues: If the validator reports errors, double-check your Cloudflare Worker configuration and JSON content. Make necessary adjustments and re-run the validation until everything passes.

This step ensures that your deep linking configurations are properly set up and recognized by mobile devices.

Want to learn more about our plugins?

Launch a full-feature native app without native development!

Plugin library

Summary

Using Cloudflare Workers to serve AASA and assetlinks files allows for a seamless way to enable app linking when your platform doesn’t support direct file hosting. Adjust the JSON data in the code as needed and manage deployment entirely through the Cloudflare dashboard.

This approach keeps your site running smoothly while ensuring your app is compatible with both Android and iOS devices. 

Once set up, validate your deep linking configuration with Median’s Deep Linking Validator to ensure your iOS and Android links are fully functional. This gives you full control over your app linking without needing to modify your existing web infrastructure.

Stay in touch

Join our mailing list for the latest mobile app news & Median updates.

Thank you for subscribing to our newsletter!

Oops! Something went wrong while submitting the form.