# Initial SDK Setup

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

You can also check out the demo on GitHub

Storyly Demo for React Native (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

Storyly React Native package is available through npm (opens new window). Source code is also available through the Storyly React Native Github page. (opens new window), contributions are more than welcomed 🙂

    # Android Installation

    Storyly SDK is developed using Kotlin language. So, there are some requirements to use Kotlin plugin in the project. Especially if you're encountering a Plugin with id 'kotlin-android' not found. error, this part fixes that.

    You need to add kotlin-gradle-plugin to Android project's main Gradle file (android/build.gradle)



     



    buildscript {
        dependencies {
            classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:1.4.30")
        }
    }
    

    Moreover, Storyly SDK is developed using the AndroidX library package instead of the Support Library. So, you need to ensure that your project also supports these packages. You can do this check and add related lines if it's missing in the application's Android project's Gradle properties file (android/gradle.properties)

    android.useAndroidX=true
    android.enableJetifier=true
    

    WARNING

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

    # iOS Installation

    Storyly React Native contains platform-specific (native) code. Autolinking is needed to be done so that your project can discover and use this code. If your application depends on react-native 0.60+, Autolinking is handled by react native as is mentioned in autolinking in react-native (opens new window). Otherwise, react-native 0.60-, please refer for detailed explanation Linking Libraries in iOS (opens new window) for correct handling of autolinking.

    // react-native 0.60-
    react-native link storyly-react-native
    

    After linking, you need to update Pods of the app;

      WARNING

      Storyly SDK targets iOS 9 or higher.

      WARNING

      Please note that CocoaPods (opens new window) version should be 1.9+

      # Import Storyly

      Importing Storyly in your React Native application is quite easy:

      import { Storyly } from 'storyly-react-native';
      

      # Initialize Storyly

      Storyly extends Component so that you can use inherited functionality as it is. You can add the following lines inside any view of your app;

      <Storyly
        style={{ width: '100%', height: 120 }}
        ref={ref => { this.storyly = ref }}
        storylyId=STORYLY_INSTANCE_TOKEN/>      
      

      WARNING

      storylyId: It's required for your app's correct initialization.

      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.

      # Storyly Event Handling

      This guide 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, user redirections, user interaction.

      Before you begin

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

      # Storyly Events

      Storyly component notifies application when an event occurs. You can register the callback functions using the following code example. Moreover, you can chech the next sections to learn more about details of the events.

      <Storyly
        ...
        onLoad={storyGroupList => console.log("[Storyly] onLoad")}
        onFail={errorMessage => console.log("[Storyly] onFail")}
        onStoryOpen={() => console.log("[Storyly] onStoryOpen")}
        onStoryClose={() => console.log("[Storyly] onStoryClose")}
        onPress={story => console.log("[Storyly] onPress")}
        onEvent={eventPayload => console.log("[Storyly] onEvent")}
        onUserInteracted={console.log("[Storyly] onStoryUserInteracted")}
      />
      

      # OnLoad 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:

      <Storyly
        ...
        onLoad={storyGroupList => {
          // console.log(storyGroupList.nativeEvent);
          console.log("[Storyly] onLoad");
        }}
      />
      

      Check storyGroupList.nativeEvent member of function parameter:

      [
        {
          "id": 1,
          "title": "...",
          "index": 1,
          "seen": true,
          "iconUrl": "...",
          "stories": [
            {
              "id": 1,
              "title": "...",
              "index": 1,
              "seen": true,
              "media": {
                "type": 1,
                "url": "...",
                "actionUrl": null
              }
            }
          ]
        }
      ]
      

      # OnFail 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:

      <Storyly
        ...
        onFail={errorMessage => {
          console.log("[Storyly] onFail");
        }}
      />
      

      # 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 storylyTestMode is false, you need to explicitly define to set test devices.

      <Storyly
        style={{ width: '100%', height: 120 }}
        ref={ref => { this.storyly = ref }}
        storylyId=STORYLY_INSTANCE_TOKEN/>
        storylyTestMode={true}