Getting Started

Getting started with Player is simple.

Install Dependencies

The first dependency you’ll need to pull in is the Player itself. Additionally, you’ll need an assets plugin to define any UI — we’ll use the reference assets as an example.

You can do this by running

yarn add @player-ui/react
yarn add @player-ui/reference-assets-plugin-react

npm install @player-ui/react
npm install @player-ui/reference-assets-plugin-react

In your Podfile you’ll need to add PlayerUI as a dependency and the ReferenceAssets plugin to use the base set of assets.

source 'https://github.com/player-ui/player'

target 'MyApp' do
  # Add the pod to your target
  pod 'PlayerUI'
  pod 'PlayerUI/ReferenceAssets' # For example only
end

Configure the Android Player dependencies in your build.gradle(.kts) files.

dependencies {
    // Android Player
    implementation("com.intuit.player.android:player:$playerVersion")
    // Optional - reference assets
    implementation("com.intuit.player.android:assets:$playerVersion")
}

The reference assets aren't intended for production use. They exist as an example of how to create assets and can be used to help get started.

Next, in your code you’ll need to initialize Player. This is where you would also initialize any plugins you want to use with Player and create the configuration for Player itself. Below is a minimal example of this.

import { ReactPlayer } from '@player-ui/react';
import { ReferenceAssetsPlugin } from '@player-ui/reference-assets-plugin-react';

// create a new web-player instance

const reactPlayer = new ReactPlayer({
  plugins: [new ReferenceAssetsPlugin()],
});

SwiftUIPlayer is just a normal SwiftUI View and can be inserted anywhere in your hierarchy.

import PlayerUI

var body: some View {
  SwiftUIPlayer(
    plugins: [ReferenceAssetsPlugin()],
  )
}

// create Android Player with reference assets plugin
val player = AndroidPlayer(ReferenceAssetsPlugin())

Render Content

Now that you have a Player instance created. You’ll need to start it with some content.

const content = {/* your content here */}
reactPlayer.start(content);

With Player running your content, you’ll need to actually render out what is processes. To do this, you can use the React Player’s component API to insert it into your React tree.

const MyApp = () => {
  return <reactPlayer.Component />;
};

Expanding on the SwiftUIPlayer creation above, providing a flow will start the Player automatically, and the result will update the Binding<Result<CompletedState, PlayerError>?> that you pass to it:

import PlayerUI

struct MyApp: View {
  @State var result: Result<CompletedState, PlayerError>? = nil
  @ObservedObject var viewModel: MyViewModel
  var body: some View {
    SwiftUIPlayer(
      flow: $viewModel.flowString,
      plugins: [ReferenceAssetsPlugin()],
      result: $result
    )
  }
}

To receive view updates, you must add a handler to render the views which are represented as RenderableAssets.

// handle view updates - should be done before starting the Player
player.onUpdate { asset: RenderableAsset? ->
    // render asset as View `into` view tree
    asset?.render() into binding.playerContainer
}

// start Player
player.start(content)

When you’re done with Player, release any native runtime memory used to instantiate Player or run the flow.

player.release()

Creating your own AndroidPlayer instance is fairly simple, but it grows in complexity when considering proper resources management and app orchestration. We provide a Fragment/ViewModel integration to make it easier to properly integrate into your app and account for these concerns.

ViewModel

With the PlayerViewModel and PlayerFragment, the above orchestration is done for you. All that is needed is to provide concrete implementations of each and add the fragment to your app.

PlayerViewModel

The PlayerViewModel requires an AsyncFlowIterator to be supplied in the constructor. The AsyncFlowIterator is what tells Player which flows to run. This can be hardcoded into the view model or expected as an argument, as shown below.

class SimplePlayerViewModel(flows: AsyncFlowIterator) : PlayerViewModel(flows) {
    override val plugins = listOf(ReferenceAssetsPlugin())
}

PlayerFragment

The PlayerFragment is a simple Android Fragment that only requires a specific PlayerViewModel to be defined. If your view model requires the AsyncFlowIterator to be passed as part of the constructor, you can leverage the PlayerViewModel.Factory to produce it, as shown below.

Specifically, this fragment takes a flow as an argument to the constructor and creates a single-flow AsyncFlowIterator instance using the pseudo-constructor helper.

class SimplePlayerFragment(override val flow: String) : PlayerFragment() {
    override val playerViewModel by viewModels<SimplePlayerViewModel> {
        PlayerViewModel.Factory(AsyncFlowIterator(flow), ::SimplePlayerViewModel)
    }
}

Congrats! You’ve got Player up and running. If you need additional functionality you can add more plugins to extend Player’s functionality. Head over to the Plugins section to take a look at the Plugins we’ve developed or take a look at the Architecture section to see how you can write your own.