> For the complete documentation index, see [llms.txt](https://docs.perkox.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.perkox.com/getting-started/sdk/perkox-flutter-sdk.md).

# Perkox Flutter SDK

The Perkox Flutter SDK allows you to integrate the Perkox offerwall into your Flutter applications. Written in Dart, it provides native performance on both Android and iOS from a single codebase.

## Installation

Add the Perkox Flutter SDK to your `pubspec.yaml`:

```yaml
dependencies:
  perkox_sdk: ^1.0.0
```

Then run:

```bash
flutter pub get
```

## Initialization

Import and initialize the SDK in your app:

```dart
import 'package:perkox_sdk/perkox_sdk.dart';

void main() {
  Perkox.initialize(
    apiKey: 'YOUR_API_KEY',
    appId: 'YOUR_APP_ID',
  );
  runApp(MyApp());
}
```

## Show the Offerwall

Display the offerwall to your users:

```dart
Perkox.showOfferwall(
  context: context,
  playerId: 'user_12345',
  onReward: (reward) {
    setState(() {
      userBalance += reward.amount;
    });
  },
);
```

## Server-Side Postback (Recommended)

For secure reward validation, configure a server-side postback URL in the Perkox dashboard. Perkox sends a server-to-server callback when a user completes an offer:

```
https://yourapp.com/api/perkox/postback?user_id={user_id}&amount={amount}&tx_id={tx_id}&offer_id={offer_id}&status={status}
```

The postback is signed with your secret key. Always verify the signature on your server before crediting rewards. See the Postback URL Configuration guide for details.

## Configuration Options

| Parameter    | Type     | Required | Description                     |
| ------------ | -------- | -------- | ------------------------------- |
| apiKey       | String   | Yes      | Your Perkox API key             |
| appId        | String   | Yes      | Your app ID from dashboard      |
| playerId     | String   | Yes      | Unique user identifier          |
| currencyName | String   | No       | Virtual currency name           |
| onReward     | Function | No       | Callback when user earns reward |

## Platform Setup

### Android

The SDK automatically configures Android. No additional setup required beyond the Flutter plugin installation.

### iOS

Add the following to your ios Podfile if not already present:

```ruby
target 'YourApp' do
  use_frameworks!
  pod 'PerkoxSDK'
end
```

Then run:

```bash
cd ios && pod install
```

## Offerwall Entry Point

Add an Earn Coins button in your app shop or store screen:

```dart
ElevatedButton(
  onPressed: () {
    Perkox.showOfferwall(
      context: context,
      playerId: currentUserId,
    );
  },
  child: Text('Earn Coins'),
)
```

## Testing

Before going live, test the offerwall integration:

1. Use your test API key from the Perkox dashboard
2. Complete a test offer to verify the postback
3. Check that the reward is credited correctly
4. Verify the postback signature on your server

## Troubleshooting

**Offerwall not showing:** Ensure you have initialized the SDK with valid API key and app ID.

**Rewards not crediting:** Check your postback URL configuration and server-side validation.

**Build errors on iOS:** Run pod install in the ios directory after adding the dependency.

## Support

Need help? Contact us at <support@perkox.com> or visit pub.perkox.com.

## Next Steps

* Postback URL Configuration
* Currency Configuration
* Design Customization
* SDK Overview