Artery
Log In Get Access
Docs L33
Log In Get Access

react-native-artery Setup

The @l33solutions/react-native-artery package collects health data from HealthKit (iOS) and Health Connect (Android), syncs it to the Artery API, and supports connecting third-party wearable providers (Garmin, Fitbit, Whoop) via OAuth.

Requirements

  • iOS 15.0 or later
  • Android API 26 (Android 8.0) or later
  • React Native (any version — peer dependency)
  • An Artery tenant account and API key

Installation

Install the package and its required peer dependency:

npm install @l33solutions/react-native-artery @react-native-async-storage/async-storage

Initialise the Client

Call ArteryClient.init() once at app startup before any other SDK method. The client is static — there is no constructor.

import { ArteryClient } from '@l33solutions/react-native-artery';

ArteryClient.init({
  apiKey: 'YOUR_API_KEY',
  userId: hashUserId(currentUser.id), // Must be hashed — no PII
  environment: 'production',           // or 'sandbox'
  oauthCallbackScheme: 'myapp',        // Required only for OAuth provider connections
});

Requesting Permissions

On iOS this shows the HealthKit permission sheet. On Android it opens the Health Connect permission activity.

const permissions = await ArteryClient.requestPermissions([
  'steps',
  'heart_rate',
  'active_calories',
  'sleep_session',
]);

// permissions: { steps: 'granted', heart_rate: 'denied', ... }

Fetching Health Data

Reads health data for one type within a date range and sends it to the Artery API. Returns the number of data points sent.

const result = await ArteryClient.fetchData('steps', {
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31'),
});

console.log(`Sent ${result.pointsSent} data points`);

Background Sync

Register OS-level observers that automatically push new health data whenever the OS delivers it, even when the app is in the background.

await ArteryClient.enableBackgroundSync(['steps', 'heart_rate', 'active_calories']);

Call syncNow() when the app comes to the foreground to catch up any delayed data and drain the offline queue:

import { AppState } from 'react-native';

AppState.addEventListener('change', async (state) => {
  if (state === 'active') {
    await ArteryClient.syncNow();
  }
});

Error Handling

All async methods throw ArteryError on failure. Wrap calls in try/catch and switch on err.code:

import { ArteryClient, ArteryError } from '@l33solutions/react-native-artery';

try {
  await ArteryClient.fetchData('steps', { startDate, endDate });
} catch (err) {
  if (err instanceof ArteryError) {
    switch (err.code) {
      case 'not_initialised':  /* init() was not called */ break;
      case 'unavailable':      /* HealthKit/Health Connect not available */ break;
      case 'auth_error':       /* invalid or revoked API key (HTTP 401) */ break;
      case 'network_error':    /* no connectivity — data queued for retry */ break;
      case 'validation_error': /* malformed payload (HTTP 400) */ break;
      case 'server_error':     /* API returned 5xx after all retries */ break;
      case 'oauth_error':      /* OAuth flow failed */ break;
    }
  }
}

Next Steps

Once your app is syncing data, configure Webhooks to receive push notifications whenever new health events are ingested — no polling required.

Next → Webhooks