Snoopr API

Reference for the Snoopr API methods.

Overview

The Snoopr object provides methods to display Stories, identify users, and track events.

import { Snoopr } from 'react-native-snoopr'

Displaying Stories

showStory()

Display the live Story for your app.

const response = await Snoopr.showStory(options?)

Parameters:

OptionTypeDefaultDescription
showOnlyOncebooleantrueIf true, Story shows once per installation
onFinish(response) => void-Called when Story completes (including dismiss on final screen)
onDismiss() => void-Called when Story is dismissed early (before final screen)

Returns: Promise<StoryResponse>

interface StoryResponse {
  completed: boolean              // true when Story finishes (includes dismiss on final screen)
  contentId: string               // Unique ID for this story
  selections: Record<string, string[]>  // Selection element values
  toggles: Record<string, boolean | Record<string, boolean>>  // Toggle values
}

Note: Dismissing on the final screen is treated as completion and delivers all collected responses. The Snoopr dashboard enforces that the last screen has a Close button, making this the expected completion path.


**Examples:**

```tsx
// Basic usage - shows once
await Snoopr.showStory()

// With callbacks
await Snoopr.showStory({
  onFinish: (response) => {
    // Called on completion OR dismiss on final screen
    console.log('Finished:', response.selections)
  },
  onDismiss: () => {
    // Only called if user dismisses before reaching final screen
    console.log('User exited early')
  }
})

// Force show every time (for testing)
await Snoopr.showStory({ showOnlyOnce: false })

User Identification

identify()

Associate a user ID with the current session. Use this after login.

Snoopr.identify(userId, properties?)

Parameters:

ParameterTypeRequiredDescription
userIdstringYesYour user's unique ID
propertiesUserPropertiesNoAdditional user attributes

Example:

// After login
Snoopr.identify('user-123', {
  plan: 'premium',
  signupDate: '2024-01-15'
})

setUserProperties()

Update user properties without changing the user ID.

Snoopr.setUserProperties(properties)

Example:

Snoopr.setUserProperties({
  completedOnboarding: true,
  preferredLanguage: 'es'
})

reset()

Clear user state. Call this on logout.

await Snoopr.reset()

This clears:

  • User ID
  • User properties
  • Completion history (Stories will show again)

Completion State

hasCompleted()

Check if a user has completed specific content.

const completed = await Snoopr.hasCompleted(contentId)

Example:

const hasSeenOnboarding = await Snoopr.hasCompleted('story:app-xxx:v1')

if (!hasSeenOnboarding) {
  await Snoopr.showStory()
}

resetCompleted()

Reset completion state to allow content to show again.

// Reset specific content
await Snoopr.resetCompleted('story:app-xxx:v1')

// Reset all completions
await Snoopr.resetCompleted()

Event Tracking

trackEvent()

Track custom events for trigger-based Stories (future feature).

await Snoopr.trackEvent(eventName, properties?)

Example:

await Snoopr.trackEvent('purchase_completed', {
  amount: 49.99,
  product: 'premium_plan'
})

trackScreenView()

Track screen views for analytics.

await Snoopr.trackScreenView(screenName)

Example:

await Snoopr.trackScreenView('ProductDetails')

Testing Integration

testIntegration()

Verify your SDK setup is working.

const result = await Snoopr.testIntegration()

Returns:

{
  success: boolean
  alreadyIntegrated?: boolean
  integratedAt?: string
  error?: string
}

Example:

const result = await Snoopr.testIntegration()

if (result.success) {
  console.log('SDK connected!')
} else {
  console.error('Setup issue:', result.error)
}

Use devMode={true} on SnooprProvider to run this automatically on startup.

Legacy Methods

These methods exist for backward compatibility. Use showStory() for new integrations.

showScreen()

Display a specific carousel by ID.

await Snoopr.showScreen(carouselId, options?)

dismissScreen()

Programmatically close the current carousel.

Snoopr.dismissScreen()

hasSeenScreen()

Check if a carousel has been viewed.

const seen = await Snoopr.hasSeenScreen(carouselId)

markScreenAsSeen()

Mark a carousel as viewed without displaying it.

await Snoopr.markScreenAsSeen(carouselId)