# In-App Experiences for the Android SDK

Integrate Scenes & In-App Automations into your Android app to display embedded content and create custom in-app experiences with minimal code.

In-App Experiences use Airship's on-device automation framework to provide instant, personalized content that integrates natively with your app. This includes [Scenes](https://www.airship.com/docs/reference/glossary/#scene), which can be displayed as modal or fullscreen overlays or embedded directly within your app screens, and In-App Automations (IAA), which power banner, modal, and fullscreen in-app messages triggered by events.

<!-- TODO: Add image: scenes-overview.png - Examples of Scenes: modal overlay, fullscreen, and embedded in app screen -->

Scenes are fully customizable in the Airship dashboard and require minimal SDK integration. For advanced In-App Automation customization options, see [In-App Automation](https://www.airship.com/docs/developer/sdk-integration/android/in-app-experiences/in-app-automation/).

## Requirements

To use In-App Experiences, you need:

- The `urbanairship-automation` module installed (see [Getting Started](https://www.airship.com/docs/developer/sdk-integration/android/installation/getting-started/))
- Airship SDK initialized (see [Getting Started](https://www.airship.com/docs/developer/sdk-integration/android/installation/getting-started/))

> **Note:** **In-App Experiences work out of the box**: Once you install the `urbanairship-automation` module and initialize Airship, In-App Experiences will function automatically. The rest of this documentation covers optional customization and advanced features.


## Controlling display

Control when and how In-App Experiences are displayed in your app. You can auto-pause displays on launch (useful for splash screens), manually pause all in-app displays, set intervals between displays, and control when individual messages are ready to display.

### Auto-pausing on launch

For apps with splash screens, you can configure Airship to automatically pause In-App Automation on launch. This prevents In-App Experiences from displaying during the splash screen. Once your app is ready, resume display by setting `isPaused` to `false`.

Set the `autoPauseInAppAutomationOnLaunch` option in your Airship config when building `AirshipConfigOptions` (in your Autopilot's `createAirshipConfigOptions` or in `airshipconfig.properties` as `auto_pause_in_app_automation_on_launch = true`):


#### Kotlin


```kotlin
override fun createAirshipConfigOptions(context: Context) =
    airshipConfigOptions {
        // ... other config settings ...

        // Auto-pause on launch for splash screen
        setAutoPauseInAppAutomationOnLaunch(true)
    }
```


When your splash screen is dismissed and the app is ready, resume display:

```kotlin
InAppAutomation.shared().isPaused = false
```



#### Java


```java
@Override
public AirshipConfigOptions createAirshipConfigOptions(Context context) {
    return AirshipConfigOptions.newBuilder()
            // ... other config settings ...

            // Auto-pause on launch for splash screen
            .setAutoPauseInAppAutomationOnLaunch(true)

            .build();
}
```


When your splash screen is dismissed and the app is ready, resume display:

```java
InAppAutomation.shared().setPaused(false);
```




### Pausing display

Pausing will still allow In-App Experiences to be triggered and queued up 
for execution, but they will not display. This is useful for preventing in-app experiences from
displaying on screens where it would be detrimental to the user experience,
such as splash screens, settings screens, or landing pages.


#### Kotlin


```kotlin
InAppAutomation.shared().isPaused = true
```



#### Java


```java
InAppAutomation.shared().setPaused(true);
```




### Display interval

The display interval controls the amount of time to wait before the manager can display the next triggered In-App Experience. The default value is set to **0 seconds** and can be adjusted to any amount of time in seconds.


#### Kotlin


```kotlin
InAppAutomation.shared().inAppMessaging.displayInterval = 30
```



#### Java


```java
InAppAutomation.shared().getInAppMessaging().setDisplayInterval(30);
```




### Controlling per-message display

You can control when individual In-App Experiences are ready to display and listen for when they are displayed or finished. This is useful when you need to check app state before displaying content, such as:

- Verifying the current Activity is appropriate for the message
- Checking custom data in the message's extras (custom keys) to determine if it should display
- Ensuring certain app conditions are met before showing the message
- Integrating with other in-app messaging products


#### Kotlin



Set a delegate to control the display. You have access to the message and schedule ID:

```kotlin
InAppAutomation.shared().inAppMessaging.displayDelegate = object : InAppMessageDisplayDelegate {
    override fun isMessageReadyToDisplay(message: InAppMessage, scheduleId: String): Boolean {
        // Return false to prevent display
        return false
    }

    override fun messageWillDisplay(message: InAppMessage, scheduleId: String) {
        // Message displayed
    }

    override fun messageFinishedDisplaying(message: InAppMessage, scheduleId: String) {
        // Message finished
    }
}
```


`isMessageReadyToDisplay` will be called whenever state in the app changes (Activity, app state, message finished displaying, etc...), you can also trigger it manually with `notifyDisplayConditionsChanged`:

```kotlin
InAppAutomation.shared().inAppMessaging.notifyDisplayConditionsChanged()
```




#### Java



Implement the `InAppMessageDisplayDelegate` to control the display. You have access to the message and schedule ID:

**Implement the InAppMessageDisplayDelegate**


```java
InAppAutomation.shared().getInAppMessaging().setDisplayDelegate(new InAppMessageDisplayDelegate() {
    @Override
    public boolean isMessageReadyToDisplay(@NonNull InAppMessage message, @NonNull String scheduleId) {
        // Return false to prevent display
        return false;
    }

    @Override
    public void messageWillDisplay(@NonNull InAppMessage message, @NonNull String scheduleId) {
        // Message displayed
    }

    @Override
    public void messageFinishedDisplaying(@NonNull InAppMessage message, @NonNull String scheduleId) {
        // Message finished
    }
});
```


`isMessageReadyToDisplay` will be called whenever state in the app changes (Activity, app state, message finished displaying, etc...), you can also trigger it manually with `notifyDisplayConditionsChanged`:

```java
InAppAutomation.shared().getInAppMessaging().notifyDisplayConditionsChanged();
```





## Next steps

- Learn how to [create Scenes in the Airship dashboard](https://www.airship.com/docs/guides/messaging/in-app-experiences/scenes/create/)
- Present Scene content with [Embedded Content](https://www.airship.com/docs/developer/sdk-integration/android/in-app-experiences/embedded-content/)
- Create reusable components with [Custom Views](https://www.airship.com/docs/developer/sdk-integration/android/in-app-experiences/custom-views/)
- Customize [In-App Automation](https://www.airship.com/docs/developer/sdk-integration/android/in-app-experiences/in-app-automation/) for IAA