Session Attributes

Beta release

The Sauce Mobile Beta SDK can attach key-value attributes to a session, which helps you generate better insights and lets you search sessions by your own values.

Android
iOS
React Native

TestFairy.setAttribute("<key>", "<value>");

Example

// Be sure to import the SDK
import com.testfairy.TestFairy;

TestFairy.setAttribute("payment-method","free");
TestFairy.setAttribute("account-type","driver");
TestFairy.setAttribute("phone","+1-672-154-5109");
TestFairy.setAttribute("level","20");

[TestFairy setAttribute:@"<key>" withValue:@"<value>"];

Example

// Be sure to import the SDK
#import "TestFairy.h"

[TestFairy setAttribute:@"name" withValue:@"John Snow"];
[TestFairy setAttribute:@"phone" withValue:@"+672-14-5109"];
[TestFairy setAttribute:@"age" withValue:@"20"];
[TestFairy setAttribute:@"favorite_color" withValue:@"blue"];

Swift

import TestFairy

TestFairy.setAttribute("name", withValue: "John Snow")
TestFairy.setAttribute("favorite_color", withValue: "blue")

TestFairy.setAttribute("<key>", "<value>");

Example

// Be sure to import the SDK
import TestFairy from '@saucelabs/mobile-beta-react-native';

TestFairy.setAttribute("name","John Snow");
TestFairy.setAttribute("phone","+672-14-5109");
TestFairy.setAttribute("age","20");
TestFairy.setAttribute("favorite_color","blue");

The first value is a string key to help you search for the attribute in your session. The second parameter, value, is any string value for the attribute associated with the session. Neither value can be nil. These attributes are available later in the session recording page, are available via API, and are searchable.

Adding these lines will mark this session with the values above, so when you review the recording, you have more information about the person running the app.

note

setAttribute may be called many times.
You may call setAttribute before or after beginWithoutCrashHandler (or begin). Attributes set before the session starts are kept by the SDK and applied to every session it starts, including the new session created after stop() and resume.
Limits: 64 attributes per session, keys of up to 64 characters, and values of up to 1000 characters on iOS and 1024 characters on Android. On Android and iOS, setAttribute returns a boolean and returns false when the attribute is rejected, for example when the limit is exceeded.

Reserved Attributes for Backtrace Coexistence

When you run the SDK together with Backtrace (Sauce Labs Error Reporting), a small set of attributes is shared by both SDKs so that a crash report in Backtrace and the session recording in Sauce Labs Mobile App Distribution can be joined. Treat these keys as reserved: set them with setAttribute before beginWithoutCrashHandler, send the same values to Backtrace, and do not reuse the keys for anything else.

Attribute	Meaning
`sauce.correlation_id`	One lowercase UUID v4 generated per app launch before either SDK starts. It is the join key between a Backtrace report and its session.
`sauce.sdk.coexistence_mode`	Always `backtrace_crash_owner`: Backtrace owns crash reporting and the SDK does not install a crash handler.
`sauce.environment`	Deployment environment of the build, for example `beta` or `production`.
`sauce.release`	Release identifier in the form `<appId>@<version>` (application or bundle ID and marketing version).
`sauce.dist`	Build number (`versionCode` on Android, `CFBundleVersion` on iOS).
`mad.distribution_id`	The Mobile App Distribution distribution ID. Set it only when your build is distributed through it.

// Android example; the keys and values are identical on iOS and React Native.
String correlationId = UUID.randomUUID().toString(); // generated before either SDK starts

TestFairy.setAttribute("sauce.correlation_id", correlationId);
TestFairy.setAttribute("sauce.sdk.coexistence_mode", "backtrace_crash_owner");
TestFairy.setAttribute("sauce.environment", "beta");
TestFairy.setAttribute("sauce.release", BuildConfig.APPLICATION_ID + "@" + BuildConfig.VERSION_NAME);
TestFairy.setAttribute("sauce.dist", String.valueOf(BuildConfig.VERSION_CODE));
TestFairy.beginWithoutCrashHandler(getApplicationContext(), "<sauce-mobile-beta-token>");

The reverse link is written on the Backtrace side only: on every session start, the app copies the session URL into the Backtrace attributes sauce.mobile_beta.session_url and sauce.mobile_beta.session_started ("true" or "false") from a session state listener (TestFairy.addSessionStateListener on Android and React Native, TestFairy.setSessionStateDelegate on iOS). A launch can produce several sessions (stop() followed by resume), so overwrite these values on every start. Never set them once.

Do not use the deprecated setCorrelationId or identify for sauce.correlation_id: they write the user-identity field, not an attribute. Keep setUserId for the real user. See Identifying Your Users.

In Backtrace, a custom attribute becomes filterable once it is indexed under Project Settings, Attributes (see Backtrace attributes). Index sauce.correlation_id with the UUID format. In the Sauce Labs Mobile App Distribution dashboard, search the session list for the same value. The initialization order and complete examples for each platform are in Using Sauce Mobile Beta with Backtrace.

Reserved Attributes for Backtrace Coexistence​

Reserved Attributes for Backtrace Coexistence