# Initial SDK Setup

This walkthrough shows how to add Storyly to your Android application and show your first story in it.

You can also check out the demo on GitHub

Storyly Demo for Kotlin (opens new window)

Storyly Demo for Java (opens new window)

Before you begin

This walkthrough contains sample instance information. However, if you want to work with your own content as well, please login into Storyly Dashboard (opens new window) and get your instance token.

The sample instance information for testing purposes;

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJhY2NfaWQiOjc2MCwiYXBwX2lkIjo0MDUsImluc19pZCI6NDA0fQ.1AkqOy_lsiownTBNhVOUKc91uc9fDcAxfQZtpm3nj40

# Installation

First, declare the dependency for the Storyly SDK in your app’s module Gradle file (usually app/build.gradle).





 




android {
    dependencies {
        ...
        // You should add this line
        implementation 'com.appsamurai.storyly:storyly:<latest-version>'
        ...
    }
}

TIP

Please do not forget to replace <latest-version>. The latest version is Maven Central (opens new window)

WARNING

Storyly SDK targets Android API level 17 (Android 4.2, Jelly Bean) or higher.

WARNING

Please note that if you want to use the Interactive VOD feature, you need to add Java 1.8 compatibility configuration as well. In your app’s module Gradle file (usually app/build.gradle), please add the following instructions:




 
 



android {
    compileOptions {
        // You should add these two lines
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

WARNING

If your application targets devices that does not contain Google APIs, you need to initialize EmojiCompat (opens new window) class to use Emoji related features of Storyly such as Emoji and Rating Components. Otherwise, you will encounter a crash whenever you use any of these components in your Storyly instance.

Please follow Emoji Compat Bundled Fonts initialization steps (opens new window) to use Emoji features of Storyly.

# Add Storyly View

You can add StorylyView to your app either from XML layout or using the programmatic approach.

StorylyView extends ViewGroup so that you can use inherited functionality as it is. So, you can add StorylyView to any of the app’s layouts as a View component.

# Adding from XML Layout

Open your XML layout and add these lines wherever you want to add StorylyView

<com.appsamurai.storyly.StorylyView
    android:id="@+id/storyly_view"
    android:layout_width="match_parent"
    android:layout_height="wrap_content" />

# Programmatically

StorylyView extends ViewGroup so that you can use inherited functionality as it is. So, you can initialize StorylyView using View’s constructors.

    # Initialize StorylyView

    You are one step away from enjoying Storyly. You just need to initialize StorylyView.

      TIP

      Please do not forget to use your own token. You can get your token from the Storyly Dashboard -> Settings -> App Settings (opens new window)

      Just hit the run. Now, you should be able to enjoy Storyly 🎉!

      WARNING

      If you can't see Storyly in your application, please check that your token is correct. For more details please check console logs.

      # Set Up Listener

      This walkthrough shows you how to handle Storyly events in your app. Storyly events provide insight on what is happening on a Storyly instance such as loading states.

      Before you begin

      You need to have the working Storyly integration as described in Initial SDK Setup


      StorylyView notifies application when an event occurs. You can register the listener using the following code example and then override its functions to learn about specific events, which will be explained in the next sections.

        In order to get notification about these basic events, you should override the following functions in StorylyListener.

        # StorylyLoaded Event

        This event will let you know that Storyly has completed its network operations, and the story group list has just been shown to the user. In order to notified about this event, use the following example:

          # StorylyLoadFailed Event

          This event will let you know that Storyly has completed its network operations and had a problem while fetching your stories. In this case, users will see four empty story group icons, which we call skeleton view. In order to notified about this event, use the following example:

            # How to Show/Hide Storyly Bar

            This guide shows use cases for showing or hiding Storyly bar in your app. To increase user experience when there are no stories available or stories are not loading using Storyly event handling.

            You can also check out the demo on GitHub

            Storyly Demo for Kotlin (opens new window)

            Storyly Demo for Java (opens new window)

            Before you begin

            You need to have the working Storyly setup as described in Initial SDK Setup

            # Show Storyly

            show-storyly-diagram

            Use case for showing storyly if StorylyView is loaded and stories are available.

            Create layout xml with added StorylyView. Initialize StorylyView with token from dashboard.

            For not to show already visible StorylyView bar, check if initially load and storyGroupList size. Set StorylyView visibility to View.VISIBLE.

            Event handling

            storylyLoaded event triggers first for available cached stories and second for request response with current stories. Detailed information about Set Up Listener

              # Hide Storyly

              show-storyly-diagram

              Use case for hiding storyly if StorylyView is not loaded and stories are not available.

              Create layout xml with added StorylyView. Initialize StorylyView with token from dashboard.

              For not to show already visible StorylyView bar, check if initially loaded and storyGroupList size. Set StorylyView visibility to View.VISIBLE.

              Loading cached stories triggers storylyLoaded event before storylyLoadFailed event. Check for if cache loaded and storyGroupList size. If cache or request is not loaded set StorylyView visibility to View.INVISIBLE or Visibility.GONE.

              Event handling

              storylyLoaded event triggers first for available cached stories and later for up to date stories. storylyLoaded for cached stories will trigger before storylyLoadFailed.

                # Test Mode

                Before you begin

                You need to have the working Storyly integration as described in Initial SDK Setup

                This guide shows how to show test groups created in Storyly Dashboard to the specific devices. The default value of isTestMode is false, you need to explicitly define to set test devices.