How to Get the User's Public IP Address Using Web-Tracing

Web-tracing exposes an asynchronous getIPs() method that uses WebRTC STUN requests to discover the client's public IPv4 address, also caching the result in the SDK's base information object.

The web-tracing library provides a built-in mechanism to capture a user's public IP address without relying on external HTTP lookup services. By leveraging WebRTC ICE candidates and STUN server negotiation, the SDK extracts the client's routable IPv4 address directly in the browser. This capability is implemented in the framework-agnostic core package and exposed through both a standalone utility and the initialized SDK state.

How Web-Tracing Discovers the Public IP

Web-tracing does not rely on third-party IP lookup APIs. Instead, it creates a temporary RTCPeerConnection to gather ICE candidates and filter for public IP addresses.

The internal logic resides in packages/core/src/utils/getIps.ts, which initiates a WebRTC connection, collects ICE candidates, filters out private ranges (such as 192.168.x.x or 10.x.x.x), and returns the first valid public IPv4 address found.

Two Methods to Get the User's Public IP Address

Method 1: Call the getIPs() Export Directly

The most direct approach is importing and awaiting the getIPs() function exported from the main entry point. This helper is defined in packages/core/src/lib/exportMethods.ts (lines 48-53) and wraps the low-level utility to return a promise that resolves to the IP string.

import { getIPs } from 'web-tracing'

async function showPublicIp() {
  try {
    const ip = await getIPs()  // Resolves to a string like "203.0.113.42"
    console.log('Public IP:', ip)
  } catch (e) {
    console.error('Failed to obtain IP:', e)
  }
}

showPublicIp()

Method 2: Read from the BaseInfo Object

After initializing the SDK, web-tracing automatically invokes getIPs() during the base information collection phase. The resolved value is stored in the base object's ip property, accessible via the SDK's internal state.

During initialization, the BaseInfo.initBase() method in packages/core/src/lib/base.ts (lines 99-104) awaits the IP discovery and assigns it to baseInfo.base.value.ip.

import WebTracing from 'web-tracing'

WebTracing.init({
  // your InitOptions
})

// Allow time for the async IP discovery (typically < 1 second)
setTimeout(() => {
  const ip = (WebTracing as any).baseInfo.base.value.ip
  console.log('Public IP from BaseInfo:', ip)
}, 1000)

Core Implementation Files

To understand the architecture or extend the functionality, reference these source files:

• packages/core/src/utils/getIps.ts: Contains the WebRTC peer connection logic and IP filtering (private vs. public).
• packages/core/src/lib/exportMethods.ts: Exports the public getIPs() method consumed by applications.
• packages/core/src/lib/base.ts: Initializes base telemetry data and persists the IP address in the SDK state.

Summary

• WebRTC-based discovery: The library uses local STUN requests via RTCPeerConnection rather than external HTTP services.
• Dual access patterns: Retrieve the IP either by calling getIPs() directly or by reading baseInfo.base.value.ip after SDK initialization.
• Asynchronous operation: Both methods return promises because WebRTC ICE candidate gathering takes time to complete.
• Framework agnostic: The core logic works in any supported environment (Vue 2/3, React, vanilla JavaScript) as long as WebRTC APIs are available.

Frequently Asked Questions

Does web-tracing use an external API to look up the IP address?

No. According to the source code in packages/core/src/utils/getIps.ts, the library uses browser WebRTC APIs to perform local STUN requests. This avoids external HTTP dependencies and reduces latency.

Why is the getIPs() method asynchronous?

The WebRTC ICE candidate gathering process is inherently asynchronous and may take a few hundred milliseconds to complete. Both the direct getIPs() call and the internal BaseInfo initialization await this discovery phase.

What happens if the user is behind a strict NAT or VPN?

The utility filters ICE candidates to return only public IPv4 addresses. If no public IP is discoverable via WebRTC, the method may return an empty result or reject, depending on the specific network configuration and browser implementation.

Can I use this IP detection in server-side rendering (SSR) environments?

No. The WebRTC-based detection relies on browser APIs (RTCPeerConnection) and will only function in client-side browser environments. Server-side executions will not have access to WebRTC interfaces.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}