Raw map API

This page is the focused reference for the preserved raw-map API shipped in @seatlayer/react-native@0.3.4.

Public component contract

<SeatLayerView
  controller={controller}
  configuration={configuration}
  style={{ flex: 1 }}
  reloadKey={reloadKey}
  onReady={handleReady}
  onLoadError={handleLoadError}
/>

controller and configuration are required. style, reloadKey, onReady, and onLoadError are optional. The component is not a forwardRef surface.

Use reloadKey only for an intentional new chart generation. Ordinary React rerenders should keep both the controller and configuration identity unchanged.

Buyer access

The package’s dependable path is a renewable provider backed by your server:

import type { SeatLayerConfiguration } from '@seatlayer/react-native';

const configuration = useMemo<SeatLayerConfiguration>(
  () => ({
    event,
    locale: 'en',
    currency: 'USD',
    maxSelection: 6,
    buyerAccessTokenProvider: ({ reason }) =>
      buyerBackend.mintSeatLayerAccess(reason),
  }),
  [event],
);

The provider returns a short-lived BuyerAccessToken in memory. An explicit one-shot buyerAccessToken is also supported, but a provider can renew after expiry or authorization failure without rebuilding the view.

Create the native buyer-access session on your backend through buyer access sessions, return only its short-lived token to the provider, and treat SDK access details as opaque.

For Public inventory, use the matching publishable key:

const configuration = useMemo<SeatLayerConfiguration>(
  () => ({ event, publicKey: 'pk_test_your_public_key' }),
  [event],
);

Configuration map

See the tagged SeatLayerConfiguration declaration for exact types and payload models.

Subscribe to controller events

controller.on returns an unsubscribe function, so it fits directly into a React effect:

useEffect(() => {
  const stopSelection = controller.on('selectionChanged', setSelectedSeats);
  const stopExpiry = controller.on('holdExpired', returnBuyerToMap);
  const stopError = controller.on('error', reportSeatLayerError);

  return () => {
    stopSelection();
    stopExpiry();
    stopError();
  };
}, [controller]);

Event payloads are typed. Unknown future events are retained rather than crashing an older application.

The host explicitly calls hold() and hands only holdId to its backend. No map event is booking authority or should launch raw-map checkout by itself.

Common command groups

These are common task groups, not an exhaustive API substitute.

Use the tagged controller source for exact arguments, returns, and every method in 0.3.4. Gate optional host controls from negotiated bundle capabilities and handle unsupported_command; method presence alone does not prove an Event supports the feature.

Commands return promises. Catch SeatLayerError at the awaited call so a sold seat, incompatible capability, timeout, or destroyed session stays attached to the action that failed.

try {
  const hold = await controller.bestAvailable(4);
  if (hold) await checkoutBackend.begin({ holdId: hold.holdId });
} catch (error) {
  if (error instanceof SeatLayerError) {
    showInventoryMessage(error.code, error.message);
  }
}

Hold ownership

• A hold is temporary inventory ownership, not a booking.
• Keep its opaque ID out of logs and analytics.
• Call resumeHold(holdId) only when restoring a checkout your product owns.
• Treat holdExpired as authoritative even if an in-app countdown had time remaining.
• Send only holdId to the server. Cart lines and totals in the app are for display, not payment authority.

View and gesture requirements

• Give SeatLayerView a definite size.
• Do not mount it in a parent that competes for pan or pinch gestures.
• Keep application overlays accessible without intercepting the map accidentally.
• Use the SDK’s typed camera and floor commands; do not forward raw touch coordinates into the map.

Cleanup

useSeatLayerController() owns controller cleanup for the hook lifecycle. If a different integration constructs and owns a controller directly, destroy that session when its screen is permanently finished. Do not send commands after destruction.

Related pages

• React Native SDK overview
• Native picker and custom layouts
• Holds and checkout
• Lifecycle and foreground recovery
• Shared troubleshooting matrix
• Tagged example
• Tagged changelog