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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.abtasty.com/server-side/sdks/react-native/abtasty-qa-assistant-for-react-native.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.