npm package: @kolect.ai/kolect-ads-react-native
Description: Comprehensive advertising SDK for AI companion and chat app developers
Author: Kolect.ai
Latest version: 0.3.7

# Kolect ads react native 

## Developer Requirements

To use the contextual kolect ads SDK in your React Native app, you need to provide the following:

- **appId**: Your application ID from the LLM Ads dashboard
- **appSecret**: Your application secret key from the LLM Ads dashboard  
- **baseUrl**: The API base URL for your environment (optional, defaults to production)
- **placementId**: The specific ad placement identifier from your dashboard

## Installation

You also need to install the required dependency:

```bash
npm install react-native-device-info
# or
yarn add react-native-device-info
```

## Import

First, import the `LlmAdsComponent` component in your React Native app:

```tsx
import { LlmAdsComponent } from '@kolect.ai/kolect-ads-react-native';
```

## Configuration

### Maximum Wait Time

You can configure the maximum wait time for ad requests using the `maxWaitTime` prop:

- **maxWaitTime** (number, optional): Maximum wait time in seconds (default: 10)
- If the API takes longer than the specified time, no ad will be shown
- If the API returns within the time limit, the ad will be displayed immediately

Example:
```tsx
<LlmAdsComponent
  appId="your-app-id"
  appSecret="your-app-secret"
  placementId="your-placement-id"
  messageType="intention"
  adType="banner"
  message="Show relevant ads"
  maxWaitTime={10} // Wait maximum 10 seconds for ad
/>
```

## Styling

### Custom Styling

```tsx
import React from 'react';
import { View, StyleSheet } from 'react-native';
import { LlmAdsComponent } from 'kolect-ads-react-native';

const App = () => {
  return (
    <View style={styles.container}>
      <LlmAdsComponent
        appId="your-app-id"
        appSecret="your-app-secret"
        placementId="your-placement-id"
        messageType="intention"
        adType="banner"
        message="Show relevant ads"
        maxWaitTime={10}
        style={styles.adContainer}
        textStyle={styles.adText}
        sponsoredTextStyle={styles.sponsoredText}
        brandNameStyle={styles.brandName}
        loadingStyle={styles.loadingContainer}
        errorStyle={styles.errorContainer}
      />
    </View>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 20,
  },
  adContainer: {
    backgroundColor: '#ffffff',
    borderRadius: 16,
    padding: 20,
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.1,
    shadowRadius: 4,
    elevation: 3,
  },
  adText: {
    color: '#333333',
    fontSize: 16,
    fontWeight: '600',
    textAlign: 'center',
  },
  sponsoredText: {
    color: '#888888',
    fontSize: 11,
    fontWeight: '400',
    fontStyle: 'italic',
  },
  brandName: {
    color: '#007AFF',
    fontSize: 12,
    fontWeight: '700',
    textTransform: 'uppercase',
  },
  loadingContainer: {
    backgroundColor: '#f8f9fa',
    borderRadius: 16,
    padding: 20,
  },
  errorContainer: {
    backgroundColor: '#fff5f5',
    borderRadius: 16,
    padding: 20,
  },
});
```

### Styling Properties

The component supports several styling properties to customize the appearance of different elements:

- **`style`**: Styles for the main ad container
- **`textStyle`**: Styles for the ad content text
- **`sponsoredTextStyle`**: Styles for the "Sponsored" label text
- **`brandNameStyle`**: Styles for the brand name (title) in the sponsored text
- **`loadingStyle`**: Styles for the loading state container
- **`errorStyle`**: Styles for the error state container

The `sponsoredTextStyle` and `brandNameStyle` props allow you to independently customize the appearance of different parts of the sponsored label. You have full control over font size, color, weight, and other text properties for both the "Sponsored" text and the brand name separately.

## Callbacks

The SDK provides callback functions that allow you to handle ad events and make decisions based on ad content:

### Available Callbacks

#### `onAdLoaded?: (ad: AdContent) => void`
Called when an ad is successfully loaded and ready to display.

- **Parameters**: 
  - `ad`: The loaded ad content with properties:
    - `id`: Unique ad identifier
    - `body`: Ad text content
    - `destinationUrl`: URL to open on click
    - `trackingToken`: Token for event tracking
    - `title?`: Optional ad title
    - `iconUrl?`: Optional ad icon URL

**Use cases:**
- Decide whether to show the ad based on content
- Log successful ad loads for analytics
- Customize UI based on ad properties

```tsx
<LlmAdsComponent
  appId="your-app-id"
  appSecret="your-app-secret"
  placementId="your-placement-id"
  messageType="intention"
  onAdLoaded={(ad) => {
    console.log('Ad loaded:', ad.body);
    // Decide whether to show based on content
    if (ad.body.includes('inappropriate-content')) {
      // Handle inappropriate content
    }
  }}
/>
```

#### `onAdError?: (error: string) => void`
Called when an error occurs during ad loading or processing.

- **Parameters**: 
  - `error`: Error message describing what went wrong

**Use cases:**
- Handle network errors gracefully
- Log errors for debugging
- Show fallback content when ads fail
- Implement retry logic

```tsx
<LlmAdsComponent
  appId="your-app-id"
  appSecret="your-app-secret"
  placementId="your-placement-id"
  messageType="intention"
  onAdError={(error) => {
    console.error('Ad loading failed:', error);
    // Show fallback content or retry
    if (error.includes('network')) {
      // Handle network errors
      showNetworkErrorMessage();
    }
  }}
/>
```

### Complete Example

```tsx
import React, { useState } from 'react';
import { View, Text, Alert } from 'react-native';
import { LlmAdsComponent } from '@kolect.ai/kolect-ads-react-native';

const AdExample = () => {
  const [adStats, setAdStats] = useState({
    loaded: 0,
    errors: 0,
  });

  return (
    <View>
      <LlmAdsComponent
        appId="your-app-id"
        appSecret="your-app-secret"
        placementId="your-placement-id"
        messageType="intention"
        message="Show technology ads"
        adType="banner"
        maxWaitTime={10}
        
        onAdLoaded={(ad) => {
          console.log('✅ Ad loaded successfully:', ad.body);
        }}
        
        onAdError={(error) => {
          console.error('❌ Ad error:', error);
        }}
      />
      
      {/* Debug stats */}
      <Text>Loaded: {adStats.loaded}, Errors: {adStats.errors}</Text>
    </View>
  );
};
```

### Best Practices

1. **Error Handling**: Always implement `onAdError` to handle network issues and API failures gracefully
2. **Content Filtering**: Use `onAdLoaded` to filter inappropriate content before display
3. **User Experience**: Don't show intrusive error messages; handle errors silently when possible
4. **Performance**: Keep callback functions lightweight to avoid blocking the UI