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

> Discover a user's public IP address with web-tracing. This article explains how the getIPs method uses WebRTC STUN requests to reliably find and cache IP information.

- Repository: [m-cheng-web/web-tracing](https://github.com/m-cheng-web/web-tracing)
- Tags: how-to-guide
- Published: 2026-03-06

---

**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`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/base.ts) (lines 99-104) awaits the IP discovery and assigns it to `baseInfo.base.value.ip`.

```typescript
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`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/utils/getIps.ts)**: Contains the WebRTC peer connection logic and IP filtering (private vs. public).
- **[`packages/core/src/lib/exportMethods.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/packages/core/src/lib/exportMethods.ts)**: Exports the public `getIPs()` method consumed by applications.
- **[`packages/core/src/lib/base.ts`](https://github.com/m-cheng-web/web-tracing/blob/main/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`](https://github.com/m-cheng-web/web-tracing/blob/main/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.