npm package: @konvo-ai/sdk-rn
Description: KonvoAI Conversational Ad SDK for React Native - Intelligent contextual advertising with AI-powered decision engine for mobile apps
Author: KonvoAI
Latest version: 1.0.0

# KonvoAI React Native SDK

> Intelligent contextual advertising with AI-powered decision engine for React Native mobile apps

## Installation

```bash
npm install @konvo-ai/sdk-rn
```

Note: This SDK requires `@react-native-async-storage/async-storage` for storing anonymous user IDs. It will be installed automatically as a dependency.

For React Native projects, you may need to run:
```bash
cd ios && pod install  # iOS only
```

## Quick Start

```typescript
import { KonvoAIAds } from '@konvo-ai/sdk-rn';
import { View, Text, TouchableOpacity, StyleSheet } from 'react-native';

// Initialize the SDK
KonvoAIAds.init({
  apiKey: 'your-api-key-here'
});

const AdComponent = () => {
  const [adData, setAdData] = useState(null);

  useEffect(() => {
    loadAd();
  }, []);

  const loadAd = async () => {
    try {
      const response = await KonvoAIAds.decide({
        context: {
          domain: 'gaming',
          content: 'mobile-game-tutorial',
          placement: 'banner'
        },
        user: {
          userId: 'user123',
          anonId: await KonvoAIAds.generateAnonId()
        },
        chat: {
          lastUserMsg: 'This game is awesome!'
        }
      });

      if (response.fill && response.render) {
        setAdData(response);
        // Track impression
        await KonvoAIAds.handleImpression(response);
      }
    } catch (error) {
      console.error('Failed to load ad:', error);
    }
  };

  if (!adData) return null;

  return (
    <View style={styles.adContainer}>
      <Text style={styles.title}>{adData.render.title}</Text>
      <Text style={styles.description}>{adData.render.description}</Text>
      <TouchableOpacity 
        style={styles.ctaButton}
        onPress={adData.render.cta.handler}
      >
        <Text style={styles.ctaText}>{adData.render.cta.label}</Text>
      </TouchableOpacity>
    </View>
  );
};

const styles = StyleSheet.create({
  adContainer: {
    padding: 16,
    borderWidth: 1,
    borderColor: '#ddd',
    borderRadius: 8,
    backgroundColor: '#f9f9f9',
  },
  title: {
    fontSize: 18,
    fontWeight: 'bold',
    marginBottom: 8,
  },
  description: {
    fontSize: 14,
    color: '#666',
    marginBottom: 12,
  },
  ctaButton: {
    backgroundColor: '#007AFF',
    paddingVertical: 8,
    paddingHorizontal: 16,
    borderRadius: 4,
  },
  ctaText: {
    color: 'white',
    textAlign: 'center',
    fontWeight: '600',
  },
});
```

## API Reference

### `KonvoAIAds.init(config)`

Initialize the SDK with your API configuration.

**Parameters:**
- `config.apiKey` (string, required): Your KonvoAI API key
- `config.baseUrl` (string, optional): Custom API base URL (defaults to production)

### `KonvoAIAds.decide(input)`

Request an ad decision from the KonvoAI engine.

**Parameters:**
- `input.context` (object): Context information about the placement
  - `domain` (string): Content domain/category
  - `content` (string): Content identifier
  - `placement` (string): Ad placement identifier
- `input.user` (object): User information
  - `userId` (string, optional): Authenticated user ID
  - `anonId` (string): Anonymous user identifier
- `input.chat` (object): Chat context
  - `lastUserMsg` (string): Most recent user message for context

**Returns:** Promise<DecideResponse>
- `decisionId` (string): Unique decision identifier
- `fill` (boolean): Whether an ad should be shown
- `render` (object, optional): Ad content when fill is true
  - `title` (string): Ad headline
  - `description` (string): Ad description
  - `cta` (object): Call-to-action
    - `label` (string): Button text
    - `handler` (function): Click handler function

### `KonvoAIAds.handleImpression(response)`

Track an ad impression. Call this when the ad is displayed to the user.

**Parameters:**
- `response` (DecideResponse): The response from `decide()`

### `KonvoAIAds.generateAnonId()`

Generate or retrieve a persistent anonymous user ID stored in AsyncStorage.

**Returns:** Promise<string> - Anonymous user identifier

## Privacy & Data Handling

The KonvoAI SDK includes automatic PII scrubbing for user messages:
- Names are replaced with `[NAME]`
- Phone numbers are replaced with `[PHONE]`
- Email addresses are replaced with `[EMAIL]`
- Social Security Numbers are replaced with `[SSN]`
- Credit card numbers are replaced with `[CARD]`
- ZIP codes are replaced with `[ZIP]`

## React Native Compatibility

- Supports React Native 0.60.0 and above
- Compatible with both iOS and Android
- Uses AsyncStorage for persistent anonymous ID storage
- Handles deep linking through React Native's Linking API

## Support

- Documentation: https://docs.konvo.ai/react-native-sdk
- Issues: https://github.com/konvo-ai/sdk-rn/issues
- Email: support@konvo.ai

## License

MIT License - see LICENSE file for details.