How to Set Custom User Agent in Axios for Mobile Apps

Configuring a custom User-Agent in mobile application wrappers using Axios allows developers to accurately identify client platforms, track app versions, and implement specialized backend logic. This guide explains how to define custom User-Agent headers globally, per-instance, or per-request using the Axios HTTP client, along with handling dynamic device metadata in mobile wrapper environments like React Native and Capacitor.

Why Set a Custom User-Agent?

Mobile wrappers and hybrid frameworks often default to the underlying WebView's browser User-Agent. Overriding this header helps your backend APIs:

1. Setting a Custom User-Agent Globally

If all outgoing HTTP requests from your application should share the same User-Agent string, assign it directly to Axios defaults during your app's initialization phase.

import axios from 'axios';

// Set the global User-Agent header
axios.defaults.headers.common['User-Agent'] = 'MyMobileApp/1.0.0 (Android 14; Mobile)';

2. Setting User-Agent via a Custom Axios Instance

Creating a dedicated Axios instance is the recommended pattern for modular architecture. This keeps custom headers scoped specifically to your API service.

import axios from 'axios';

const apiClient = axios.create({
  baseURL: 'https://api.example.com/v1',
  timeout: 10000,
  headers: {
    'User-Agent': 'MyMobileApp/1.2.0 (iOS 17.4; iPhone)',
    'Content-Type': 'application/json',
  },
});

export default apiClient;

3. Dynamically Generating the User-Agent String

Hardcoding platform details can lead to outdated header information. In mobile wrapper environments, combine device information libraries with Axios request interceptors to build dynamic User-Agent headers.

React Native Example

Using a package like react-native-device-info:

import axios from 'axios';
import DeviceInfo from 'react-native-device-info';

const apiClient = axios.create({
  baseURL: 'https://api.example.com',
});

// Dynamic Interceptor
apiClient.interceptors.request.use(async (config) => {
  const appVersion = DeviceInfo.getVersion();
  const systemName = DeviceInfo.getSystemName();
  const systemVersion = DeviceInfo.getSystemVersion();
  const deviceModel = DeviceInfo.getModel();

  const customUserAgent = `MyApp/${appVersion} (${systemName} ${systemVersion}; ${deviceModel})`;

  config.headers['User-Agent'] = customUserAgent;
  return config;
}, (error) => {
  return Promise.reject(error);
});

export default apiClient;

4. Setting User-Agent for Individual Requests

To override the User-Agent for a single specific request:

import axios from 'axios';

axios.get('https://api.example.com/check-updates', {
  headers: {
    'User-Agent': 'MyApp-Updater/1.0.0',
  },
})
.then(response => console.log(response.data))
.catch(error => console.error(error));

Platform Limitations to Consider