# 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](https://docs.abtasty.com/server-side/integrations/using-abtasty-qa-assistant)

### 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

{% hint style="info" %}
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.
{% endhint %}

### Prerequisites

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

***

### Installation

{% stepper %}
{% step %}

#### Install Flagship SDK (if not already installed)

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

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

{% endstep %}

{% step %}

#### Install the Package

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

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

{% endstep %}
{% endstepper %}

### 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:

{% stepper %}
{% step %}

#### Enable QA Mode in FlagshipProvider

```tsx
// 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>
  );
}
```

{% hint style="warning" %}
The `isQAModeEnabled={true}` prop is **required**. Without it, the QA Assistant will not render.
{% endhint %}

{% endstep %}

{% step %}

#### Development-Only usage

Ensure the QA Assistant only appears in development builds:

```tsx
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>
  );
}
```

{% endstep %}
{% endstepper %}

### Configuration options

Customize the QA Assistant appearance and behavior:

```tsx
<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

```tsx
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

{% hint style="danger" %}
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
{% endhint %}

### Troubleshooting & FAQ

#### Common issues

**QA Assistant not showing**

**Checklist:**

1. **Verify `isQAModeEnabled` is set to `true`**

   ```tsx
   <FlagshipProvider isQAModeEnabled={true} {...props}>
   ```
2. **Ensure QAAssistant is inside FlagshipProvider**

   ```tsx
   <FlagshipProvider>
     <App />
     <QAAssistant />  {/* ✓ Correct placement */}
   </FlagshipProvider>
   ```
3. **Check conditional rendering**

   ```tsx
   // Verify __DEV__ is true
   console.log('__DEV__:', __DEV__);
   {__DEV__ && <QAAssistant />}
   ```
4. **Clear cache and reinstall**

   ```bash
   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.

```tsx
// ✗ 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:

```bash
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()`:

   ```tsx
   // ✗ 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**:

   ```tsx
   <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