Unity SDK API

Use the New Relic Unity SDK API to further configure and extend the plugin's instrumentation.

Install the SDK

Ensure you have your app instrumented with a current SDK for New Relic Mobile by following the installation instructions.

Create and complete interactions

To start an interaction:

string interactionIdentifier = NewRelicAgent.StartInteractionWithName("new interaction");

To stop the current interaction:

NewRelicAgent.StopCurrentInteraction(interactionIdentifier);

Interactions work in conjuction with method tracing. To trace a method insert startTracingMethod insert at the start of the method to trace, and insert endTracingMethodWithTimer at each exit point of the method.

To start tracing a method:

Timer methodTimer = new Timer();
NewRelicAgent.StartTracingMethod("MethodName","ClassName",methodTimer,NewRelicAgent.NRTraceType.None);

To end tracing a method; use the same timer as the startTracingMethod:

NewRelicAgent.EndTracingMethodWithTimer(methodTimer);

Set a custom build identifier

Custom build identifiers are set as the Application Build property in the inspector pane for the NewRelicAgent game object, under the New Relic Agent (Script) settings.

Executing a demo crash

If you have trouble getting your project to crash, the New Relic Unity plugin provides an API to execute a demo crash.

New Relic recommends adding this line of code to a button click event handler as applicable:

NewRelicAgent.CrashNow("message")

Record custom metrics

With the custom metric API, you can record arbitrary numerical data and named events. Custom metrics can help to track high level events specific to your application.

You can use several API calls to record custom metrics that provide different levels of detail. To create a custom metric, use this method:

NewRelicAgent.RecordMetricWithName(String name, String category)

The name parameter is the textual name of the metric that will appear in the user interface for New Relic Mobile. Using clear, concise metric names will help you get the most out of the metrics.

The guidelines for naming a custom metric include:

  • Use case and whitespace characters appropriate for display in the user interface. Metric names are rendered as-is.
  • Capitalize the metric name.
  • Avoid using the characters / ] [ | * when naming things.
  • Avoid multi-byte characters.

If you want to specify more details about a custom metric, three other API methods are available:

NewRelicAgent.RecordMetricWithName(String name, String category, double value)

NewRelicAgent.RecordMetricWithName(string name, string category, double value, string valueUnits)

NewRelicAgent.RecordMetricWithName(string name, string category, double value, string valueUnits, string countUnits)

With these methods, you can record additional details:

Parameter Description
count The number of times the event has happened
totalValue The total value of the recording
exclusiveValue The exclusive value of the recording; for example, if the total value contains measurements accounted for elsewhere
countUnit Unit of measurement for the metric count, including PERCENT, BYTES, SECONDS, BYTES_PER_SECOND, or OPERATIONS
valueUnit Unit of measurement for the metric value, including PERCENT, BYTES, SECONDS, BYTES_PER_SECOND, or OPERATIONS

To view the custom metrics you collect, follow standard procedures to create custom dashboards.

Send custom events/attributes to Insights

The SDK can store up to 64 user-defined attributes at a time. If you attempt to store more than 64 attributes, the SDK returns false.

Use the following static methods in the NewRelicAgent namespace to send custom attributes and events to New Relic Insights. Methods that return boolean results return true if they succeed, or false if the operation did not complete.

The following methods are available for custom attributes and events:

RecordEvent (name, attributes)
NewRelicAgent.RecordEvent (string name, string dictionary attributes)

Records a custom Insights event. Includes a list of attributes specified as a map.

SetAttribute (name, value)
NewRelicAgent.SetAttribute (string name, string value)
NewRelicAgent.SetAttribute (string name, double value)

Creates an attribute with the specified text name and text/float value. SetAttribute overwrites its previous value and type each time it is called.

Examples

boolean attributeSet = NewRelicAgent.SetAttribute("username", "SampleUserName");
boolean attributeSet = NewRelicAgent.SetAttribute("rate", 9999.99);
IncrementAttribute (name [, value])
public static boolean IncrementAttribute(String name);
public static boolean incrementAttribute(String name, double value)

If value is not specified, this method increments the count for the specified attribute by 1. If the attribute does not exist, it creates the attribute with a value of 1.

If value is specified, the method will increment the attribute by the specified amount.

Examples

boolean incremented = NewRelicAgent.IncrementAttribute("rate");
boolean incremented = NewRelicAgent.IncrementAttribute("rate", 9999.99, false);
RemoveAttribute (name)
NewRelicAgent.RemoveAttribute(String name)

Removes the specified attribute.

Example

boolean attributeRemoved = NewRelicAgent.RemoveAttribute("rate");
removeAllAttributes
NewRelicAgent.removeAllAttributes()

Removes all attributes from the session.

Example

boolean attributesRemoved = NewRelicAgent.RemoveAllAttributes();

Track custom network requests

New Relic Mobile's API provides several methods to track network requests and network failures. For example, use the noticeHttpTransaction family of methods to record HTTP transactions with several available levels of detail. If a network request fails, you can record details about the failure with noticeNetworkFailure.

NoticeNetworkRequest
NewRelicAgent.NoticeNetworkRequest ("http://newrelic.com", "GET", timer, null, 200, 1024, 8192, bytes, httpParameters);
Parameter Description
url The URL of the request
httpMethod The HTTP method used, such as GET or POST
statusCode The statusCode of the HTTP response, such as 200 for OK
timer A timer created when the network request was started
bytesSent The number of bytes sent in the request
bytesReceived The number of bytes received in the response
responseBody The response body of the HTTP response. The response body will be truncated and included in an HTTP Error metric if the HTTP transaction is an error.
params Additional parameters included in an HTTP Error metric if the HTTP transaction is an error.
NoticeNetworkFailure
NewRelicAgent.NoticeNetworkFailure(String url, String httpMethod, Timer timer, NewRelicAgent.NetworkFailureCode failureCode, String message)
Parameter Description
url The URL of the request
httpMethod The HTTP method used, such as GET or POST
timer A timer created when the network request was started
exception The exception that occurred. New Relic Mobile can automatically translate many common exceptions into network failure types.
failure The type of network failure that occurred. If an exception cannot be resolved to a network failure automatically, this method can be used to categorize the failure accurately. The values are defined by the NetworkFailure enum. Valid values include Unknown, BadURL, TimedOut, CannotConnectToHost, DNSLookupFailed, BadServerResponse, and SecureConnectionFailed.

Recommendations for learning more: