Categories

.well-known/assetlinks.json: Managing Android App Links and Reducing Server Errors

Understanding Android App Links and the Role of assetlinks.json

In today’s interconnected digital world, the relationship between websites and mobile apps is more important than ever. Android App Links allow Android apps to seamlessly handle specific web URLs, bypassing the browser for a smoother user experience. This magic is powered by the Digital Asset Links protocol, which relies on a file called assetlinks.json, hosted on a website’s server.

Have you ever spotted requests to /.well-known/assetlinks.json in your Apache logs, often paired with 404 errors? These aren’t random probes—they’re Android devices checking if your site is linked to an app. In this guide, we’ll show you how to configure your webserver with an empty assetlinks.json file to handle these requests efficiently, reducing errors and keeping your server logs clean.

What is assetlinks.json and Why Does It Matter?

The assetlinks.json file is part of the Digital Asset Links protocol, designed to verify associations between websites and Android apps. When a user clicks a link on their Android device, the system checks this file to determine if an app should handle it instead of the browser.

For a regular webserver with no associated Android apps, these requests can still occur, leading to:

1. Unnecessary 404 errors cluttering server logs
2. Wasted server resources processing missing file requests
3. Difficulty spotting genuine issues amidst error noise

By hosting an empty assetlinks.json file, you tell Android devices, “No app associations here,” in a clean, standards-compliant way. This simple step can optimize your server’s performance and prepare it for future app integrations.

The assetlinks.json File Explained

The assetlinks.json file is a JSON-formatted file that lists app associations. For a site with no linked apps, it’s as simple as an empty array:

[]

This minimal configuration satisfies the Digital Asset Links protocol, returning a valid response instead of a 404 error. When an app association is needed later, you can populate it with details like app package names and SHA256 fingerprints, but for now, the empty array keeps things tidy and efficient.

Step-by-Step Implementation Guide

Here’s how to set up an empty assetlinks.json file on your Apache server.

Step 1: Create the assetlinks.json File

Start by creating the file in a central location accessible to Apache.

sudo nano /etc/apache2/assetlinks.json

Add this content:

[]

Save and exit.

Step 2: Configure Apache to Serve the File

Create an Apache configuration file to serve this JSON file globally across all virtual hosts.

sudo nano /etc/apache2/conf-available/assetlinks.conf

Add the following:

# Global configuration for assetlinks.json across all vHosts
Alias "/.well-known/assetlinks.json" "/etc/apache2/assetlinks.json"

<Files "assetlinks.json">
    # Set the appropriate content type
    Header always set Content-Type "application/json"

This configuration:

1. Sets up an alias for /.well-known/assetlinks.json to point to your file
2. Ensures the response has the correct application/json content type

Step 3: Enable the Configuration

Activate the configuration and reload Apache:

sudo a2enconf assetlinks
sudo systemctl reload apache2

Step 4: Test the Configuration

Verify it works by checking the endpoint:

curl -I https://lexo.ch/.well-known/assetlinks.json

Expect a response like:

HTTP/2 200 
content-type: application/json

Then check the content:

curl https://lexo.ch/.well-known/assetlinks.json

It should return:

[]

Comparing Different Approaches

Let’s compare hosting an empty assetlinks.json versus other options:

Feature	Empty assetlinks.json	No File
Server-wide Implementation	Yes	N/A
Maintenance Complexity	Low	None
404 Error Reduction	Complete	None
Protocol Compliance	Yes	No
Future-Proofing	Yes	No

An empty assetlinks.json offers a low-effort, high-impact solution for most webservers.

Benefits and Use Cases

Implementing this configuration brings several advantages:

Server-Level Benefits

1. Reduced Log Clutter: Eliminates 404 errors for /.well-known/assetlinks.json
2. Lower Server Load: Serving a tiny JSON file is lighter than handling 404s
3. Easier Maintenance: One file manages requests for all sites

Future-Ready Benefits

1. Standards Compliance: Aligns with the Digital Asset Links protocol
2. Scalability: Ready for app associations without server changes

Ideal Use Cases

• Webservers hosting multiple sites
• Sites planning future app integrations
• Environments prioritizing clean logs

Troubleshooting Common Issues

If things don’t work as expected, try these fixes:

File Not Served

Symptom: 404 errors persist.

Solution: Check permissions:

sudo chown www-data:www-data /etc/apache2/assetlinks.json
sudo chmod 644 /etc/apache2/assetlinks.json

Incorrect Content Type

Symptom: Headers lack application/json.

Solution: Ensure mod_headers is enabled:

sudo a2enmod headers
sudo systemctl restart apache2

CMS Conflicts

Symptom: Works on some sites, not others (e.g., WordPress).

Solution: Ensure the alias takes precedence over CMS rules in your vhost config.

Conclusion: A Simple Fix with Lasting Impact

Setting up an empty assetlinks.json file is a quick win for any webserver. It cuts down on 404 errors, keeps your logs manageable, and aligns your site with modern web standards—all with minimal effort. Whether you’re running a single site or a multi-tenant server, this configuration is a smart move.

Have you added this to your server? Let us know how it’s worked for you in the comments!