# Android SDK basic integration guide

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

## Prerequisites

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

<TranslatedFragment id="prerequisites-android" />

## Integration steps


### 1. Set up Firebase Cloud Messaging

First, connect your Android project with Firebase:

- Open your project in Android Studio
- Navigate to **Tools > Firebase > Cloud Messaging** and click "Set up Firebase Cloud Messaging"
- Follow the wizard instructions. In the final step, the wizard will add the necessary dependencies to your `build.gradle` files

### 2. Add Pushwoosh SDK

Add the pushwoosh library dependency to your application's build.gradle:

```groovy title="build.gradle"
implementation 'com.pushwoosh:pushwoosh-firebase:6.+'
```

Replace "+" with the current version of [Pushwoosh Android SDK](https://github.com/Pushwoosh/pushwoosh-android-sdk/releases/latest)

### 3. Add Pushwoosh metadata to AndroidManifest.xml

Open your AndroidManifest.xml file and add the following metadata inside the `<application>` tag:

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

Where:
- `com.pushwoosh.appid` is your Pushwoosh Application Code
- `com.pushwoosh.apitoken` is your [Pushwoosh Device API Token](/developer/api-reference/api-access-token/#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)

### 4. Initialization code

Register for push notifications by adding this code to your initialization logic:

```java
Pushwoosh.getInstance().registerForPushNotifications()
```

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

In the Pushwoosh SDK, there are two callbacks designed for handling push notifications:
- `onMessageReceived`: This method is invoked when a push notification is received.
- `onMessageOpened`: This method is called when the user interacts with (opens) the notification

These callbacks enable developers to manage the reception and user interaction with push notifications within their applications:

```xml title="AndroidManifest.xml"
<meta-data
    android:name="com.pushwoosh.notification_service_extension"
    android:value="com.your.package.YourNotificationServiceExtension" />
```

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import android.util.Log
import com.pushwoosh.notification.NotificationServiceExtension
import com.pushwoosh.notification.PushMessage

class YourNotificationServiceExtension : NotificationServiceExtension() {
    
    override fun onMessageReceived(data: PushMessage): Boolean {
        Log.d("Pushwoosh", "onMessageReceived: ${data.toJson()}")
        return false
    }

    override fun onMessageOpened(message: PushMessage) {
        Log.d("Pushwoosh", "onMessageOpened: ${message.toJson()}")
    }

}
```
</TabItem>
<TabItem label="Java">
```java
import android.util.Log;
import com.pushwoosh.notification.NotificationServiceExtension;
import com.pushwoosh.notification.PushMessage;

public class YourNotificationServiceExtensionJava extends NotificationServiceExtension {

    @Override
    public boolean onMessageReceived(PushMessage data) {
        Log.d("Pushwoosh", "onMessageReceived: " + data.toJson());
        return false;
    }

    @Override
    public void onMessageOpened(PushMessage message) {
        Log.d("Pushwoosh", "onMessageOpened: " + message.toJson());
    }
}
```
</TabItem>
</Tabs>

### User configuration

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

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import com.pushwoosh.Pushwoosh
import com.pushwoosh.tags.TagsBundle
import java.util.Date

class Registration {

    public void afterUserLogin(User user) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance()

        // Set user ID
        if (user.getUserId() != null) {
            pushwoosh.setUserId(user.getUserId())
        }

        // Set user email
        if (user.getEmail() != null) {
            pushwoosh.setEmail(user.getEmail())
        }

        // Setting additional user information as tags for Pushwoosh
        if (user.getUserDetails() != null) {
            val details = user.getUserDetails()
            val tagsBuilder = TagsBundle.Builder()
            
            if (details.getAge() != null) {
                tagsBuilder.putInt("age", details.getAge())
            }
            
            if (details.getUserName() != null) {
                tagsBuilder.putString("name", details.getUserName())
            }
            
            if (details.lastLoginDate() != null) {
                tagsBuilder.putDate("last_login", details.getLastLoginDate())
            }
            
            // Build and send tags
            val tags = tagsBuilder.build()
            if (!tags.isEmpty()) {
                pushwoosh.setTags(tags)
            }
        }
    }
}
```
</TabItem>
<TabItem label="Java">
```java
import com.pushwoosh.Pushwoosh;
import com.pushwoosh.tags.TagsBundle;
import java.util.Date;

public class Registration {

    public void afterUserLogin(User user) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance();

        // Set user ID
        if (user.getUserId() != null) {
            pushwoosh.setUserId(user.getUserId());
        }

        // Set user email
        if (user.getEmail() != null) {
            pushwoosh.setEmail(user.getEmail());
        }

        // Set user SMS number
        if (user.getSmsNumber() != null) {
            pushwoosh.registerSMSNumber(user.getSmsNumber());
        }

        // Set user WhatsApp number
        if (user.getWhatsAppNumber() != null) {
            pushwoosh.registerWhatsappNumber(user.getWhatsAppNumber());
        }

        // Setting additional user information as tags for Pushwoosh
        if (user.getUserDetails() != null) {
            UserDetails details = user.getUserDetails();
            TagsBundle.Builder tagsBuilder = new TagsBundle.Builder();

            if (details.getAge() != null) {
                tagsBuilder.putInt("age", details.getAge());
            }

            if (details.getUserName() != null) {
                tagsBuilder.putString("name", details.getUserName());
            }

            if (details.getLastLoginDate() != null) {
                tagsBuilder.putDate("last_login", details.getLastLoginDate());
            }

            // Build and send tags
            TagsBundle tags = tagsBuilder.build();
            if (!tags.isEmpty()) {
                pushwoosh.setTags(tags);
            }
        }
    }
}
```
</TabItem>
</Tabs>

### Tags

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

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import com.pushwoosh.Pushwoosh
import com.pushwoosh.tags.TagsBundle
import java.util.List

class UpdateUser {
    public void afterUserUpdateProfile(User user) {
        val pushwoosh = Pushwoosh.getInstance()
        val tagsBuilder = TagsBundle.Builder()

        // Set list of favorite categories
        if (user.favoriteCategories != null && user.favoriteCategories.isNotEmpty()) {
            tagsBuilder.putList("favorite_categories", user.getFavoriteCategories())
        }

        // Set payment information
        tagsBuilder.putBoolean("is_subscribed", user.isSubscribed())
        tagsBuilder.putString("payment_status", user.getPaymentStatus())
        tagsBuilder.putString("billing_address", user.getBillingAddress())

        // Build and send tags
        pushwoosh.setTags(tagsBuilder.build())
    }
}
```
</TabItem>
<TabItem label="Java">
```java
import com.pushwoosh.Pushwoosh;
import com.pushwoosh.tags.TagsBundle;
import java.util.List;

public class UpdateUser {
    public void afterUserUpdateProfile(User user) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance();
        TagsBundle.Builder tagsBuilder = TagsBundle.Builder();

        // Set list of favorite categories
        if (user.getFavoriteCategories() != null && !user.getFavoriteCategories().isEmpty()) {
            tagsBuilder.putList("favorite_categories", user.getFavoriteCategories());
        }

        // Set payment information
        tagsBuilder.putBoolean("is_subscribed", user.isSubscribed());
        tagsBuilder.putString("payment_status", user.getPaymentStatus());
        tagsBuilder.putString("billing_address", user.getBillingAddress());

        // Build and send tags
        pushwoosh.setTags(tagsBuilder.build());
    }
}
```
</TabItem>
</Tabs>

### Events

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

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import com.pushwoosh.Pushwoosh
import com.pushwoosh.inapp.InAppManager
import com.pushwoosh.tags.TagsBundle
import java.util.Date

class Registration {

    public void afterUserLogin(User user) {
        if (user.getUserName() != null && user.getLastLoginDate() != null) {
            val attributes = TagsBundle.Builder()
                .putString("name", user.getUserName())
                .putDate("last_login", user.getLastLoginDate())
                .build()
            
            InAppManager.getInstance().postEvent("login", attributes)
        }
    }

    public void afterUserPurchase(User user, Product product) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance()

        // Track purchase event
        val purchaseAttributes = TagsBundle.Builder()
            .putString("product_id", product.getId())
            .putString("product_name", product.getName())
            .putDouble("price", product.getPrice())
            .putInt("quantity", product.getQuantity())
            .build()
        
        InAppManager.getInstance().postEvent("purchase", purchaseAttributes)

        // Set user tags
        val tagsBuilder = TagsBundle.Builder()
        tagsBuilder.putDate("last_purchase_date", Date())
        val lifetimeSpend = getCurrentLifetimeSpend() + product.getPrice()
        tagsBuilder.putDouble("lifetime_spend", getCurrentLifetimeSpend())
        pushwoosh.setTags(tagsBuilder.build())
    }
}
```
</TabItem>
<TabItem label="Java">
```java
import com.pushwoosh.Pushwoosh;
import com.pushwoosh.tags.TagsBundle;
import java.util.Date;

public class Registration {

    public void afterUserLogin(User user) {
        if (user.getUserName() != null && user.getLastLoginDate() != null) {
            TagsBundle attributes = new TagsBundle.Builder()
                .putString("name", user.getUserName())
                .putDate("last_login", user.getLastLoginDate())
                .build();

            Pushwoosh.getInstance().postEvent("login", attributes);
        }
    }

    public void afterUserPurchase(User user, Product product) {
        Pushwoosh pushwoosh = Pushwoosh.getInstance();

        // Track purchase event
        TagsBundle purchaseAttributes = new TagsBundle.Builder()
            .putString("product_id", product.getId())
            .putString("product_name", product.getName())
            .putDouble("price", product.getPrice())
            .putInt("quantity", product.getQuantity())
            .build();

        Pushwoosh.getInstance().postEvent("purchase", purchaseAttributes);

        // Set user tags
        TagsBundle.Builder tagsBuilder = new TagsBundle.Builder();
        tagsBuilder.putDate("last_purchase_date", new Date());
        double lifetimeSpend = getCurrentLifetimeSpend() + product.getPrice();
        tagsBuilder.putDouble("lifetime_spend", getCurrentLifetimeSpend());
        pushwoosh.setTags(tagsBuilder.build());
    }
}
```
</TabItem>
</Tabs>

### Rich Media

Rich media refers to interactive and multimedia content, such as images, videos, or HTML, used in notifications and in-app messages to enhance user engagement


To enable the **Modal Rich Media** feature, you need to configure it in your application's `AndroidManifest.xml` file by adding the following metadata entry:

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

<Tabs syncKey="code-example">
<TabItem label="Kotlin">
```kotlin
import android.util.Log
import com.pushwoosh.richmedia.RichMedia
import com.pushwoosh.richmedia.RichMediaManager
import com.pushwoosh.richmedia.RichMediaPresentingDelegate
import com.pushwoosh.inapp.view.config.ModalRichmediaConfig
import com.pushwoosh.inapp.view.config.enums.*

class MainActivity : AppCompatActivity(), RichMediaPresentingDelegate {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        RichMediaManager.setDelegate(this)

        // Configure the modal rich media
        val config = ModalRichmediaConfig()
            .setViewPosition(ModalRichMediaViewPosition.BOTTOM)
            .setPresentAnimationType(ModalRichMediaPresentAnimationType.SLIDE_UP)
            .setDismissAnimationType(ModalRichMediaDismissAnimationType.SLIDE_DOWN)
            
        // Apply the configuration
        RichMediaManager.setDefaultRichMediaConfig(config)
    }
    
    override fun shouldPresent(richMedia: RichMedia): Boolean {
        Log.d("Pushwoosh", "Rich media will be presented with: ${richMedia.content}")
        return true
    }

    override fun onPresent(richMedia: RichMedia) {
        Log.d("Pushwoosh", "Rich media has been presented: ${richMedia.content}")
    }

    override fun onClose(richMedia: RichMedia) {
        Log.d("Pushwoosh", "Rich media has been closed: ${richMedia.content}")
    }

    override fun onError(richMedia: RichMedia, pushwooshException: PushwooshException) {
        Log.e("Pushwoosh", "Failed to present rich media: ${richMedia.content}. Error: ${pushwooshException.message}")
    }
}
```
</TabItem>
<TabItem label="Java">
```java
import android.util.Log;
import com.pushwoosh.richmedia.RichMedia;
import com.pushwoosh.richmedia.RichMediaManager;
import com.pushwoosh.richmedia.RichMediaPresentingDelegate;
import com.pushwoosh.inapp.view.config.ModalRichmediaConfig;
import com.pushwoosh.inapp.view.config.enums.*;

public class MainActivity extends AppCompatActivity implements RichMediaPresentingDelegate {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        RichMediaManager.setDelegate(this);

        // Configure the modal rich media
        ModalRichmediaConfig config = new ModalRichmediaConfig()
            .setViewPosition(ModalRichMediaViewPosition.BOTTOM)
            .setPresentAnimationType(ModalRichMediaPresentAnimationType.SLIDE_UP)
            .setDismissAnimationType(ModalRichMediaDismissAnimationType.SLIDE_DOWN);

        // Apply the configuration
        RichMediaManager.setDefaultRichMediaConfig(config);
    }

    @Override
    public boolean shouldPresent(RichMedia richMedia) {
        Log.d("Pushwoosh", "Rich media will be presented with: " + richMedia.getContent());
        return true;
    }

    @Override
    public void onPresent(RichMedia richMedia) {
        Log.d("Pushwoosh", "Rich media has been presented: " + richMedia.getContent());
    }

    @Override
    public void onClose(RichMedia richMedia) {
        Log.d("Pushwoosh", "Rich media has been closed: " + richMedia.getContent());
    }

    @Override
    public void onError(RichMedia richMedia, PushwooshException pushwooshException) {
        Log.e("Pushwoosh", "Failed to present rich media: " + richMedia.getContent() + ". Error: " + pushwooshException.getMessage());
    }
}
```
</TabItem>
</Tabs>

## Troubleshooting

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