# Flutter SDK Basic integration guide

This section contains information on how to integrate the Pushwoosh Flutter SDK into your application.

## Prerequisites

To integrate the Pushwoosh Flutter SDK into your app, you will need the following:

<Aside type="note" title="Requirements">
 - A [Pushwoosh account](https://sso.pushwoosh.com/login).
 - A [Pushwoosh project](/product/first-steps/start-with-your-project/create-your-project) set up in your account.
 - **For iOS integration:**
    - An iOS platform configured to send push notifications. We recommend using the [Token-Based Authentication configuration](/developer/first-steps/connect-messaging-services/ios-configuration/ios-token-based-configuration/) as the simplest approach.
    - Set the Gateway to `Sandbox` to send pushes to a simulator.
 - **For Android integration:**
    - A [configured Android platform](/developer/first-steps/connect-messaging-services/android-configuration/android-firebase-configuration)
    - The `google-services.json` file and `package name` from your Firebase project.
    - A Firebase project connected to your Android application. Follow the [Firebase setup guide](https://firebase.google.com/docs/android/setup#manually_add_firebase) if needed.
 - Your `Pushwoosh Application Code` and [Pushwoosh Device API Token](/developer/api-reference/api-access-token/#device-api-token) from the Pushwoosh Control Panel for your application.
</Aside>

## Integration steps

### 1. Add Pushwoosh Flutter SDK Dependency

Add the `pushwoosh_flutter` package to your `pubspec.yaml` file:

```yaml title="pubspec.yaml"
dependencies:
  flutter:
    sdk: flutter
  # Use the latest version from https://pub.dev/packages/pushwoosh_flutter
  pushwoosh_flutter: ^[LATEST_VERSION]
```
Check the [latest version](https://pub.dev/packages/pushwoosh_flutter) on pub.dev.

Then, run the following command in your project's root directory to install the dependency:

```bash
flutter pub get
```

Double check that the package is installed correctly:
```bash
flutter pub deps | grep pushwoosh_flutter

# Example output:
# ❯ flutter pub deps | grep pushwoosh_flutter
# └── pushwoosh_flutter 2.3.11
```

### 2. Flutter SDK Initialization

In the root component of your `main.dart` file:
- Import the `pushwoosh_flutter` package.
- Initialize the Pushwoosh SDK.
- Call `registerForPushNotifications()` in your initialization logic to register for push notifications.

```dart title="main.dart"
import 'package:pushwoosh_flutter/pushwoosh_flutter.dart';

void main() async {
  runApp(const MyApp());
  Pushwoosh.initialize({
    "app_id": "__YOUR_APP_ID__"
  });
  Pushwoosh.getInstance.registerForPushNotifications();
}
```

Where:
- `__YOUR_APP_ID__` is the application code from the Pushwoosh Control Panel.


### 3. iOS Native Setup

#### 3.1 Capabilities

To enable Push Notifications in your project, you need to add certain capabilities.

In the Signing & Capabilities section, add the following capabilities:
- `Push Notifications`
- `Background Modes`. After adding this capability, check the box for `Remote notifications`.

If you intend to use Time Sensitive Notifications (iOS 15+), also add the `Time Sensitive Notifications` capability.

#### 3.2 Info.plist

In your `Runner/Info.plist` set the `__PUSHWOOSH_DEVICE_API_TOKEN__` key to the [Pushwoosh Device API Token](/developer/api-reference/api-access-token/#device-api-token):
```swift title="info.plist"
<key>Pushwoosh_API_TOKEN</key>
<string>__PUSHWOOSH_DEVICE_API_TOKEN__</string>
```

#### 3.3 Message delivery tracking

You must add a Notification Service Extension target to your project. This is essential for accurate delivery tracking and features like Rich Media on iOS. 

Follow the [native guide’s steps](/developer/pushwoosh-sdk/ios-sdk/setting-up-pushwoosh-ios-sdk/basic-integration-guide/#4-message-delivery-tracking) to add the extension target and the necessary Pushwoosh code within it.

To ensure, that Notification Service Extension is properly integrated in your Flutter project, you need to use the following Podfile configuration:

```ruby title="Podfile"
target 'NotificationServiceExtension' do
  use_frameworks!
  use_modular_headers!

  pod 'PushwooshXCFramework'

  inherit! :search_paths
end
```

#### 3.4 Installing dependencies for the iOS Flutter project

To install dependencies for the iOS Flutter project, run the following command:

```bash
flutter run
```

or navigate to the ```ios``` folder in the terminal and run:

```bash
pod install --repo-update
```

### 4. Android Native Setup

#### 4.1 Install dependencies

Ensure that the required dependencies and plugins are added to your Gradle scripts:

Add the Google Services Gradle plugin to your project-level `build.gradle` dependencies:

```groovy title="android/build.gradle"
buildscript {
  dependencies {
    classpath 'com.google.gms:google-services:4.3.15'
  }
}
```

Apply the plugin in your app-level `build.gradle` file:

```groovy title="app/build.gradle"
apply plugin: 'com.google.gms.google-services'
```

#### 4.2 Add Firebase configuration file

Place the `google-services.json` file into `android/app` folder in your project directory.

#### 4.3 Add Pushwoosh metadata

In your `main/AndroidManifest.xml` add [Pushwoosh Device API Token](/developer/api-reference/api-access-token/#device-api-token) inside the  `<application>` tag:

```xml title="AndroidManifest.xml"
<meta-data android:name="com.pushwoosh.apitoken" android:value="__YOUR_DEVICE_API_TOKEN__" />
```

> **Important:** Be sure to give the token access to the right app in your Pushwoosh Control Panel. [Learn more](/developer/api-reference/api-access-token/#edit-token)

### 5. Run the Project

1. Build and run the project.
2. Go to the Pushwoosh Control Panel and [send a push notification](/product/messaging-channels/push-notifications/send-push-notifications/one-time-push).
3. You should see the notification in the app.

## Extended integration

At this stage, you have already integrated the SDK and can send and receive push notifications. Now, let’s explore the core functionality

### Push notification event listeners

In the Pushwoosh SDK there are two event listeners, designed for handling push notifications:

- `onPushReceived` event is triggered, when a push notification is received
- `onPushAccepted` event is triggered, when a user opens a notification

You should set up these event listeners right after initialization of the SDK at the application start up:

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

class PushwooshNotificationHandler {
  void setupPushListeners(Pushwoosh pushwoosh) {

    pushwoosh.onPushReceived.listen((event) {
      print("Push received: ${event.pushwooshMessage.payload}");
    });

    pushwoosh.onPushAccepted.listen((event) {
      print("Push accepted: ${event.pushwooshMessage.payload}");
    });
    
  }
}
```

### User configuration

By focusing on individual user behavior and preferences, you can deliver personalized content, leading to increased user satisfaction and loyalty

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

class Registration {
  void afterUserLogin(User user) {
  
    // Set user ID
    Pushwoosh().setUserId(user.getId());
    
    // Set user email
    Pushwoosh().setEmail(user.getEmail());

    // Register SMS number
    // The SMS and WhatsApp numbers must be in E.164 format (e.g., "+1234567890") and be valid
    Pushwoosh().registerSmsNumber(user.getSmsNumber());

    // Register WhatsApp number
    Pushwoosh().registerWhatsappNumber(user.getWhatsappNumber());
    
    // Setting additional user information as tags for Pushwoosh
    Pushwoosh().setTags({
      "age": user.getAge(),
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }
}
```

### Tags

Tags are key-value pairs assigned to users or devices, allowing segmentation based on attributes like preferences or behavior, enabling targeted messaging.

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

class UpdateUser {
  void afterUserUpdateProfile(User user) {

    // Set list of favorite categories
    Pushwoosh().setTags({
      "favorite_categories": user.getFavoriteCategoriesList()
    });
    
    // Set payment information
    Pushwoosh().setTags({
      "is_subscribed": user.isSubscribed(),
      "payment_status": user.getPaymentStatus(),
      "billing_address": user.getBillingAddress()
    });
  }
}
```

### Events

Events are specific user actions or occurrences within the app that can be tracked to analyze behavior and trigger corresponding messages or actions

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

class Registration {

  // Track login event
  void afterUserLogin(User user) {
    Pushwoosh().postEvent("login", {
      "name": user.getName(),
      "last_login": user.getLastLoginDate()
    });
  }

  void afterUserPurchase(Product product) {

  // Track purchase event
  Pushwoosh().postEvent("purchase", {
    "product_id": product.getId(),
    "product_name": product.getName(),
    "price": product.getPrice(),
    "quantity": product.getQuantity()
  });
 }
}
```

## Using ProGuard

<Aside type="note">
Note that the `flutter build apk` command obfuscates your code by default. 
</Aside>

Thus, you may get this exception:

```java
java.lang.IllegalStateException: Could not find class for name: com.pushwoosh.plugin.PushwooshNotificationServiceExtension
```

There are two solutions in this case:

1. Use the `flutter build apk --no-shrink` command to compile your code without obfuscation.  
2. Or you can manually enable ProGuard and add the necessary rules.

To enable ProGuard for your project, add the following strings to your `build.gradle` file:

```java title="build.gradle"
buildTypes {
        release {
            minifyEnabled true
            useProguard true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'

            signingConfig signingConfigs.debug
        }
    }
```

Then, add the following rules to the `android/app/proguard-rules.pro`

```java title="proguard-rules.pro"
#Pushwoosh Flutter
-keep class com.pushwoosh.plugin.PushwooshPlugin { *; }
-keep class com.pushwoosh.plugin.PushwooshNotificationServiceExtension { *; }
```


## Troubleshooting

If you encounter any issues during the integration process, please refer to the [support and community](/developer/pushwoosh-sdk/support-and-community) section.