ABTasty QA Assistant for React Native

This guide covers the integration of the ABTasty QA Assistant into React Native applications. For usage instructions, see the QA Usage Guide

Overview

What is ABTasty QA Assistant?

The ABTasty QA Assistant is a visual testing tool for React Native applications that integrates with ABTasty Feature Experimentation. It provides a floating UI overlay that allows developers and QA engineers to test campaign variations and feature flags without backend changes or app redeployment.

Key features

• Force variations: Switches to a specific variation within a campaign

• Force allocation: Makes a rejected campaign available for testing

• Hide campaign: Hide accepted campaigns to test exclusion scenarios

• Real-time event monitoring: Track all SDK events for integration verification

• Context inspection: View visitor data and targeting rules

• Search & filter: Quickly find specific campaigns and events

Forced allocations, variations, and hidden campaigns are temporary and reset when you disable QA mode or restart the app. Everything returns to natural allocation automatically.

Prerequisites

Requirement	Minimum Version
React Native	>= 0.70.0
React	>= 18.0.0
Flagship React Native SDK	>= 5.0.2

---

Installation

1

Install Flagship SDK (if not already installed)

# Using npm
npm install @flagship.io/react-native-sdk

# Using yarn
yarn add @flagship.io/react-native-sdk

2

Install the Package

# Using npm
npm install @abtasty/qa-assistant-react-native

# Using yarn
yarn add @abtasty/qa-assistant-react-native

Dependencies

The QA Assistant has the following dependencies:

Peer Dependencies (must be installed separately):

• @flagship.io/react-native-sdk >= 5.0.2

• react >= 18.0.0

• react-native >= 0.70.0

Integration

Quick start

Add the QA Assistant to your app in two steps:

1

Enable QA Mode in FlagshipProvider

// Import FlagshipProvider from the Flagship React Native SDK
import { FlagshipProvider } from '@flagship.io/react-native-sdk';
// Import QAAssistant from the QA Assistant package
import { QAAssistant } from '@abtasty/qa-assistant-react-native';

export default function App() {
  return (
    // Wrap your app with FlagshipProvider to enable the Flagship SDK
    <FlagshipProvider
      envId="YOUR_ENV_ID"         // Your ABTasty environment ID
      apiKey="YOUR_API_KEY"       // Your ABTasty API key
      isQAModeEnabled={true}      // REQUIRED: enables the QA Assistant overlay
      visitorData={{
        id: 'visitor_id',         // Unique identifier for the visitor
        hasConsented: true,       // GDPR consent flag
        context: { platform: 'mobile' }  // Targeting context attributes
      }}
    >
      <YourApp />
      {/* Mount QAAssistant inside FlagshipProvider so it can access the SDK */}
      <QAAssistant />
    </FlagshipProvider>
  );
}

The isQAModeEnabled={true} prop is required. Without it, the QA Assistant will not render.

2

Development-Only usage

Ensure the QA Assistant only appears in development builds:

export default function App() {
  return (
    <FlagshipProvider {...props}>
      <YourApp />
      {/* Render QAAssistant only in development mode (__DEV__ is true in dev builds).
          This prevents the overlay from being bundled in production releases. */}
      {__DEV__ && <QAAssistant />}
    </FlagshipProvider>
  );
}

Configuration options

Customize the QA Assistant appearance and behavior:

<QAAssistant
  config={{
    position: "bottom-right",  // "top-right" | "top-left" | "bottom-right" | "bottom-left"
  }}
/>

Available positions:

• "top-right" - Top right corner

• "top-left" - Top left corner

• "bottom-right" - Bottom right corner (default)

• "bottom-left" - Bottom left corner

Complete example

import React from 'react';
import { StyleSheet, View, Text } from 'react-native';
// useFsFlag lets you read feature flag values reactively from the SDK
import { FlagshipProvider, useFsFlag } from '@flagship.io/react-native-sdk';
import { QAAssistant } from '@abtasty/qa-assistant-react-native';

function MyApp() {
   // Retrieve the 'welcome_message' feature flag; falls back to 'Welcome!' if not set
  const welcomeMessage = useFsFlag('welcome_message');
  // Retrieve the 'show_new_feature' boolean flag; defaults to false
  const showNewFeature = useFsFlag('show_new_feature');

  return (
    <View style={styles.container}>
      <Text style={styles.title}>
        {/* Display the flag value, or the default fallback if the flag is missing */}
        {welcomeMessage.getValue('Welcome!')}
      </Text>
      {/* Conditionally render the new feature based on the flag value */}
      {showNewFeature.getValue(false) && (
        <Text>New Feature Enabled</Text>
      )}
    </View>
  );
}

export default function App() {
  // FlagshipProvider initializes the SDK and makes flags available to all children
  return (
    <FlagshipProvider
      envId="YOUR_ENV_ID"       // Replace with your ABTasty environment ID
      apiKey="YOUR_API_KEY"     // Replace with your ABTasty API key
      isQAModeEnabled={true}    // Enable QA mode so the assistant overlay can render
      visitorData={{
        id: 'test_visitor_123', // Visitor identifier used for bucketing
        hasConsented: true,     // Must be true for the SDK to send data
        context: {
          platform: 'mobile',   // Custom context key used in targeting rules
          userType: 'free'      // Additional attribute for targeting
        }
      }}
    >
      <MyApp />
      {/* Only include QAAssistant in development builds to avoid production exposure */}
      {__DEV__ && (
        <QAAssistant config={{ position: "bottom-right" }} />
      )}
    </FlagshipProvider>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1, padding: 20 },
  title: { fontSize: 24, fontWeight: 'bold' }
});

Best practices

DO:

• Always use isQAModeEnabled={true} in FlagshipProvider

• Place QAAssistant inside FlagshipProvider

• Use conditional rendering (__DEV__) to exclude from production

• Use SDK hooks to ensure flag changes are reactive

DON'T:

• Never include QA Assistant in production builds

• Don't place QA Assistant outside FlagshipProvider

• Don't hardcode flag values - always use SDK hooks

The QA Assistant should NEVER be included in production builds. Always use conditional rendering with __DEV__ or environment variables. Exposing QA mode in production allows anyone to: - View all campaign configurations - Force any variation - See internal feature flags - Monitor SDK events

Troubleshooting & FAQ

Common issues

QA Assistant not showing

Checklist:

1. Verify isQAModeEnabled is set to true

   <FlagshipProvider isQAModeEnabled={true} {...props}>

2. Ensure QAAssistant is inside FlagshipProvider

   <FlagshipProvider>
     <App />
     <QAAssistant />  {/* ✓ Correct placement */}
   </FlagshipProvider>

3. Check conditional rendering

   // Verify __DEV__ is true
   console.log('__DEV__:', __DEV__);
   {__DEV__ && <QAAssistant />}

4. Clear cache and reinstall

   rm -rf node_modules && yarn install
   npx react-native start --reset-cache

Console warnings

Warning: "Not able to access Flagship SDK instance"

Cause 1: QAAssistant is not a direct child of FlagshipProvider.

Solution: Move QAAssistant inside FlagshipProvider.

// ✗ Wrong
<>
  <FlagshipProvider {...props}>
    <App />
  </FlagshipProvider>
  <QAAssistant />
</>

// ✓ Correct
<FlagshipProvider {...props}>
  <App />
  <QAAssistant />
</FlagshipProvider>

Cause 2: Flagship React Native SDK version is incompatible (< 5.0.2).

Solution: Update to SDK version >= 5.0.2:

npm install @flagship.io/react-native-sdk@latest
# or
yarn add @flagship.io/react-native-sdk@latest

Warning: "QA mode not enabled"

Solution: Add isQAModeEnabled={true} to FlagshipProvider.

Warning: "No valid envId configured"

Solution: Verify envId prop is set correctly in FlagshipProvider.

Campaigns not appearing

Possible Causes:

1. No campaigns configured - Check ABTasty platform

2. Network issues - Verify bucketing.json loads correctly

3. Wrong environment - Ensure using correct envId

4. SDK initialization - Wait a few seconds after app launch

Forced Variations not applying

Solutions:

1. Use SDK hooks - Ensure you're using useFsFlag():

   // ✗ Wrong - hardcoded
   const message = "Welcome";
   
   // ✓ Correct - using SDK
   const messageFlag = useFsFlag('welcome_message');
   const message = messageFlag.getValue('Welcome');

2. Verify correct variation - Check that the forced variation contains the expected flag modifications

3. Reset and retry - Clear forced variations and try again

Floating button overlapping UI

Solutions:

1. Changeposition:

   <QAAssistant config={{ position: "top-left" }} />

Frequently asked questions

Q: Do forced allocations persist after app restart? A: NO! All forced allocations, hidden campaigns, and variations are temporary and reset automatically when:

• You disable QA mode (set isQAModeEnabled={false})

• You restart the app

This is by design to ensure a clean state and prevent accidental forced states in production.

Q: Can I force multiple campaigns at once? A: Yes, each forced variation, allocation, and hidden campaign is independent.

Q: What's the difference between forcing a variation, allocation, and hiding a campaign?

Action	When to Use	Effect
Force Variation	Campaign is accepted or forced	Switch between variations
Force Allocation	Campaign is rejected	Enable variation forcing (badge changes to "Forced", stays in Rejected section)
Hide Campaign	Campaign is accepted	Hide accepted campaign (test exclusion)

Q: Can I use QA Assistant in production? A: NO! Always use conditional rendering ({__DEV__ && <QAAssistant />}) to exclude it from production.

Q: Does QA Assistant work offline? A: Initial load requires network to fetch campaigns. After that, it works offline with cached data.

Q: Can I force variations programmatically? A: QA Assistant is for manual testing. For automated tests, use Flagship SDK methods directly with controlled context values.

Additional resources

• Usage Guide: See qa-use.md for detailed usage instructions

• Flagship SDK Documentation: https://docs.developers.flagship.io/

• Support: For issues or questions, contact ABTasty support