Native HTTP API

This guide explains how to manually report HTTP requests made via a Cordova HTTP plugin or a custom native transport.

What you can do

• Report a single completed HTTP request via reportWebRequest
• Provide request/response headers, status text, and timing
• Correlate the request with a distributed trace via a W3C traceParent

Prerequisites

• RUM is enabled for your application
• The Cordova HTTP module is enabled in your RUM configuration (the module string contains K).

reportWebRequest must be called after the request finishes. It reports a completed request — it does not wrap one.

API approaches

You can use the Native HTTP API directly, or via its synchronous or asynchronous SDK functions, matching the pattern established in the RUM JavaScript SDK Overview:

Safe Wrapper API (recommended)

Use the safe wrapper from SDK.nativeHttp (@dynatrace/rum-javascript-sdk/api/native-http):

import * as nativeHttp from "@dynatrace/rum-javascript-sdk/api/native-http";

const start = Date.now();
myHttpPlugin.post({ url: "https://api.example.com/orders", body }, (response) => {
    nativeHttp.reportWebRequest({
        url: "https://api.example.com/orders",
        method: "POST",
        startTime: start,
        duration: Date.now() - start,
        statusCode: response.status,
        statusText: response.statusText,
        requestHeaders: { "Content-Type": "application/json" },
        responseHeaders: response.headers
    });
});
Copy

Async API

Use the promise-based wrapper from SDK.promises.nativeHttp (@dynatrace/rum-javascript-sdk/api/promises/native-http):

import { reportWebRequest } from "@dynatrace/rum-javascript-sdk/api/promises/native-http";

const start = Date.now();
const response = await myHttpPlugin.get("https://api.example.com/users");

await reportWebRequest({
    url: "https://api.example.com/users",
    method: "GET",
    startTime: start,
    duration: Date.now() - start,
    statusCode: response.status
});
Copy

Direct API (via dynatrace.nativeHttp)

Access the API directly through the global dynatrace.nativeHttp namespace:

const start = Date.now();
myHttpPlugin.get("https://api.example.com/users", (response) => {
    dynatrace?.nativeHttp?.reportWebRequest({
        url: "https://api.example.com/users",
        method: "GET",
        startTime: start,
        duration: Date.now() - start,
        statusCode: response.status
    });
});
Copy

ReportWebRequestOptions

See API.ReportWebRequestOptions for the full type. url, method, startTime, duration, and statusCode are required; the rest are optional.

Field	Type	Required	Description
url	string	yes	Full URL of the request
method	string	yes	HTTP method: "GET", "POST", "PUT", "PATCH", "DELETE", etc.
startTime	number	yes	Unix timestamp in milliseconds when the request started (e.g. Date.now() captured before the request)
duration	number	yes	Duration of the request in milliseconds
statusCode	number	yes	HTTP status code. Use 0 for aborted requests and a negative value for Cordova-internal errors
statusText	string	no	Human-readable status text (e.g. "OK", "Not Found")
requestHeaders	Record<string, string>	no	Headers sent with the request
responseHeaders	Record<string, string>	no	Headers received in the response
traceParent	string	no	W3C traceparent value used to correlate with a distributed trace. Format: "00-<traceId>-<spanId>-<flags>"

Error classification

The statusCode determines whether the resulting RUM event carries an error flag:

Status	Result
200–399	No error
>= 400	Error with source CORDOVA_HTTP
0	Error with source CORDOVA_HTTP, reason ABORT
-1 (GENERIC)	Error with source CORDOVA_HTTP, reason GENERIC
-2 (SSL_EXCEPTION)	Error with source CORDOVA_HTTP, reason SSL_EXCEPTION
-3 (SERVER_NOT_FOUND)	Error with source CORDOVA_HTTP, reason SERVER_NOT_FOUND
-4 (TIMEOUT)	Error with source CORDOVA_HTTP, reason TIMEOUT
-5 (UNSUPPORTED_URL)	Error with source CORDOVA_HTTP, reason UNSUPPORTED_URL
-6 (NOT_CONNECTED)	Error with source CORDOVA_HTTP, reason NO_NETWORK
-7 (POST_PROCESSING_FAILED)	Error with source CORDOVA_HTTP, reason POST_PROCESSING_FAILED
-8 (ABORTED)	Error with source CORDOVA_HTTP, reason ABORT

Distributed tracing

Pass a W3C traceParent to link the reported request to the corresponding server-side trace span:

nativeHttp.reportWebRequest({
    url: "https://api.example.com/data",
    method: "GET",
    startTime: start,
    duration: Date.now() - start,
    statusCode: response.status,
    traceParent: "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
});
Copy

Invalid or malformed traceParent values are silently ignored — no error is thrown.

URL exclusion

If a request-exclusion pattern is configured in the agent, URLs matching the pattern are silently dropped and no RUM event is emitted. The exclusion check runs inside reportWebRequest, so the call itself always succeeds.

API reference

See API.NativeHttp for the full type reference. Safe wrapper: SDK.nativeHttp • Async wrapper: SDK.promises.nativeHttp