User Info

A User Info is a dictionary queued for background delivery. Unlike Application Context, every User Info is delivered, in order, even when the Watch isn't reachable. Use it when every value matters, such as each completed workout.

Each User Info you send is a Transfer until it's delivered:

• transferUserInfo starts one and returns its Transfer snapshot.
• outstandingUserInfoTransfers lists the ones not delivered yet.
• cancelUserInfoTransfer cancels one by its id.
• onUserInfoTransferFinished fires exactly once per Transfer: when it's delivered, fails or is cancelled.

Inbound User Info from the Watch arrives through onUserInfoReceived.

A dictionary's values must be ones WatchConnectivity can carry: strings, numbers, booleans, arrays and nested objects.

transferUserInfoCopy Anchor Link

transferUserInfo<T extends Record<string, any>>(userInfo: T): OutstandingUserInfoTransfer

Queues a User Info for delivery to the Watch and returns at once. The Watch app receives it in session(_:didReceiveUserInfo:).

Type parameters

Parameters

Returns the Transfer snapshot, in the same shape as outstandingUserInfoTransfers:

The type is OutstandingUserInfoTransfer. The older name UserInfoTransfer is a deprecated alias of it.

Throws (synchronously):

Delivery failures don't throw here: they arrive later, in onUserInfoTransferFinished.

Example

import RnWatchConnect from "rn-watch-connect";

const transfer = RnWatchConnect.transferUserInfo({ workout: "run", km: 5.2 });
        
const transfer: OutstandingUserInfoTransfer
console.log("Queued Transfer", transfer.id);

cancelUserInfoTransferCopy Anchor Link

cancelUserInfoTransfer(transferId: string): { id: string }

Cancels an outstanding User Info Transfer. Its onUserInfoTransferFinished event is sent immediately, with error.code "ERR_TRANSFER_CANCELLED".

Parameters

Returns { id: string }: the id of the cancelled Transfer.

Throws (synchronously):

Its error message starts with Expo's prefix, "Calling the 'cancelUserInfoTransfer' function has failed", so match on code.

If the Transfer was delivered just before you cancel, the cancel throws ERR_INVALID_TRANSFER_ID and the finish event reports the delivery, with error: null.

Example

import RnWatchConnect, { type WatchConnectErrorCode } from "rn-watch-connect";

const transfer = RnWatchConnect.transferUserInfo({ draft: true });

try {
  RnWatchConnect.cancelUserInfoTransfer(transfer.id);
} catch (error) {
  const code = (error as { code?: WatchConnectErrorCode }).code;
  if (code === "ERR_INVALID_TRANSFER_ID") {
    // Already delivered or cancelled: nothing to do.
  }
}

outstandingUserInfoTransfersCopy Anchor Link

readonly outstandingUserInfoTransfers: OutstandingUserInfoTransfer[]

The User Info Transfers that haven't been delivered yet, as Transfer snapshots (id, userInfo, isTransferring). It's [] when there are none, and on platforms other than iOS.

Example

import RnWatchConnect from "rn-watch-connect";

// At launch: pick up Transfers from the previous run, with their new ids.
for (const transfer of RnWatchConnect.outstandingUserInfoTransfers) {
  console.log("Still queued:", transfer.id, transfer.userInfo);
}

onUserInfoReceivedCopy Anchor Link

onUserInfoReceived: (userInfo: Record<string, any>) => void

Fires when a User Info arrives from the Watch. The listener gets the dictionary itself. User Info arrives in the order the Watch sent it.

Example

import { useEventListener } from "expo";
import RnWatchConnect from "rn-watch-connect";

export function WorkoutInbox() {
  useEventListener(RnWatchConnect, "onUserInfoReceived", (userInfo) => {
    console.log("Workout from the Watch:", userInfo.workout);
  });
  return null;
}

onUserInfoTransferFinishedCopy Anchor Link

onUserInfoTransferFinished: (event: UserInfoTransferFinishedEvent) => void

Fires exactly once per User Info Transfer, however it ends. The event is the Transfer snapshot plus error:

If your Watch app is uninstalled during a Transfer, the Transfer stays outstanding and no finish event is sent, even after a reinstall. Cancel it to end it, for example when onWatchAppInstallChanged reports isWatchAppInstalled: false.

Example

import { useEventListener } from "expo";
import RnWatchConnect from "rn-watch-connect";

export function UserInfoTransferLog() {
  useEventListener(RnWatchConnect, "onUserInfoTransferFinished", (transfer) => {
    if (transfer.error?.code === "ERR_TRANSFER_CANCELLED") {
      console.log("Cancelled:", transfer.id);
    } else if (transfer.error) {
      console.log("Failed:", transfer.id, transfer.error.code);
    } else {
      console.log("Delivered:", transfer.id);
    }
  });
  return null;
}