Custom Assets

One of the conscious design decisions we made when building Player was to abstract away the actual asset implementation and open it up for users to bring their own when using Player. This way you can seamlessly integrate Player into your existing experiences and reuse UI assets you may have already built. Below we’ve outlined the way to build custom assets on the various platforms Player supports.

Create Your Asset

First and foremost you need to create a component to handle rendering of your asset. Without any form of transforms, the props to the component will be those from the incoming player content. It’s recommended that you attach the id, and any other html properties to the root of the asset’s tree:

const CustomAssetComp = (props) => {
  return (
    <div id={props.id} style={{ color: 'purple' }}>
      {props.text}
    </div>
  );
};

Assuming your authored JSON has a string property named text, this will render that.

Register it Using a Plugin

Now that we have a React component to render our asset, let’s create a plugin to register with Player:

class CustomAssetPlugin implements ReactPlayerPlugin{
  applyReact(reactPlayer) {
    new WebAssetProvider([['custom', CustomAssetComp]]).applyReact(reactPlayer);
  }
}

Typically you register assets by type, but the registry acts by finding the most specific partial object match. This allows you to register more specific implementations for assets of the same type.

Rendering Nested Assets

Often times, assets contain a reference or slot to another asset. For this to function properly, the custom asset needs to defer to the React Player to render the sub-asset. Say for instance we change our custom asset to now support a header property that takes another asset.

Use the ReactAsset Component from the @player-ui/react package with the nested asset as props to dynamically determine the rendering implementation to use:

import { ReactAsset } from '@player-ui/react';

const CustomAssetComp = (props) => {
  return (
    <div id={props.id} style={{ color: 'purple' }}>
      {props.header && <ReactAsset {...props.header} />}
      {props.text}
    </div>
  );
};

This would automatically find the appropriate handler for the props.header asset and use that to render.

SwiftUI Player assets are made of 3 parts:

Data: Decodable AssetData
View: A SwiftUI View
Asset: SwiftUIAsset implementation to tie the two together

Data

SwiftUI Player relies on assets decoding data that conforms to AssetData, this is necessary, because id and type are needed to determine what registered Swift type to decode to. You can include any decodable types in this struct as needed to match the structure of the asset that is returned from the core player.

Beyond this, there are a few wrapper types that handle some player specific features:

ModelReference

ModelReference is a wrapper that gets the raw JSValue from Player for a specific node in your asset data. This wrapper exists because if a reference to the data model is used in content, such as:

{
  "asset": {
    "id": "someId",
    "type": "text",
    "value": "{{count}}"
  }
}

While count will not necessarily be a string, in the underlying JavaScript layer, if the entire string value is just a reference to the data model, it is replaced with the exact value from the data model. This means that if count is a number in the data model, when you receive it in the swift layer it will be an Int. So ModelReference gives you a quick helper to get it as a string:

struct TextData: AssetData {
  var id: String
  var type: String
  var value: ModelReference
}
...
textData.value.stringValue

You can also access someModelReference.rawValue if you need to access the underlying JSValue for some other casting.

WrappedFunction

JavaScript plugins loaded into the core player, when you have a plugin that extends JSBasePlugin, can transform the resolved asset before it reaches the Swift layer. In many situations, this results in functions being added to an asset to ensure that the same functionality is used on all platforms, and reduce code duplication. WrappedFunction gives you a light wrapper to help decode and call those functions. It takes generic parameter that defines the return type of the function:

struct ActionData: AssetData {
  var id: String
  var type: String
  var run: WrappedFunction<Void>
}

// You can pass any number of arguments to the function
// so it's important to know what the transform added function
// expects

data.run()
data.run("arg1", 2)

WrappedAsset

Last but not least, WrappedAsset represents another asset being defined as a part of this asset. This will be a very common pattern as Player content is intended to be semantic and dynamic. Therefore we need to know that there is an asset in our data, but not what it is, as the implementation is not guaranteed.

struct ActionData: AssetData {
  var id: String
  var type: String
  var label: WrappedAsset
  var run: WrappedFunction<Void>
}

Rendering these nested assets will be described below.

View

The view for a SwiftUI Asset is a regular SwiftUI View. Any standard SwiftUI components and concepts will work as normal. The only differentiating factor when it comes to Player assets, is the WrappedAsset and rendering it. WrappedAsset contains a SwiftUIAsset?, so in the event it was not decodable, it will be nil, otherwise, you can access it’s view property to get a type-erased AnyView and render it in your view:

struct ActionView: View {
  var body: some View {
    Button(action: {}, label: {
      if let label = decodedAssetData.label.asset {
        label.view
      }
    })
  }
}

Asset

The SwiftUIAsset is the glue between the View and the Data. Player will handle decoding data, and updating the data in an ObservableObject viewModel that contains the Data you tell it to decode.

UncontrolledAsset

The UncontrolledAsset is uncontrolled because you do not specify a viewModel type, and receive an implicit AssetViewModel<T: AssetData>.

class ActionAsset: UncontrolledAsset<ActionData> {
    // Populated for you, but copied here for reference
    @ObservedObject var model: AssetViewModel<ActionData>
}

ControlledAsset

The ControlledAsset lets you define the viewModel type, as long as it subclasses AssetViewModel<T: AssetData>, this way you still receive updated data and user info whenever Player changes state, but you can add other functionality to the viewModel.

class ActionViewModel: AssetViewModel<ActionData> {
    public required init(_ data: ActionData, userInfo: [CodingUserInfoKey: Any]) {
      super.init(data, userInfo: userInfo)
    }
}
class ActionAsset: ControlledAsset<ActionData, ActionViewModel> {
    // Populated for you, but copied here for reference
    @ObservedObject var model: ActionViewModel
}

Linking the View

In either situation, your asset implementation needs only to override the view property and return the type erased view you want to use.

class ActionAsset: UncontrolledAsset<ActionData> {
        public override var view: AnyView { AnyView(ActionView(model: model)) }
}

Additional Topics

Interacting with the Data Model without a transform

If data needs to be set or retrieved without the use of a transform, the InProgressState is available in an environment object, where the DataController can be accessed, as well as other utilities:

struct SomeView: View {
  @Environment(\.inProgressState) var state: InProgressState?
  var body: some View {
    Button(action: {
      state?.controllers?.data.set(["count": 5])
    }, label: {...})
  }
}

If your experience will be used on multiple platforms, it is not advised to use this method, a transform will ensure the same logic is followed on all 3 platforms and is strongly encouraged.

Registering your Asset

When registering your asset with an AssetRegistry, it can either be registered as a new type, if it is an entirely new construct, or registered as a variant of an existing asset type, to only be rendered under certain conditions.

// Convenience function for just registering for type
player.assetRegistry.register("example", asset: ExampleAsset.self)

player.assetRegistry.register(["type": "example", "metaData": ["role": "someRole"]], for: ExampleAsset.self)

In the latter case, it is recommended to extend the original asset, so as to avoid boilerplate for data and construction, and just override the render function. If your variant will have additional data decoded that the original asset does not have, you will need to create the whole asset.

Why Would I Register my Asset as a Variant?

Transform backed assets have functions that are attached to them, through shared JavaScript plugins. This simplifies setting data from the asset, by giving simple functions like run in the reference ActionAsset for example. Swift only asset types will not have any convenience functions.
Registering as a variant allows you to maintain usage of the transform backed asset as well as your new asset, so both can be used by the same SwiftUIPlayer instance, including in the same flow. This also maintains the semantics of Player content, an action asset is always an action type of interaction, but with metaData, it can be displayed differently.

In order to render an asset a renderer for that type must be registered in the Android Player. If a renderer is found, then Player will delegate rendering when that type is encountered, otherwise Player will skip that node. Creating and registering such a renderer requires the following:

Extending DecodableAsset

DecodableAsset is a subclass of RenderableAsset that contains data decoding capabilities built on Kotlinx Serialization. This is the recommended approach for creating an asset and will be consolidated with RenderableAsset in future versions of the Android Player. On top of the requirements for subclassing RenderableAsset, subclassing DecodableAsset requires passing a KSerializer<Data> for the data class that represents the data for that asset.

RenderableAsset is the base structure used by Player to convert parsed content into Android Views. Each implementation is instantiated with an AssetContext and is required to implement two methods, initView and hydrate. The separation of logic between these two methods allow for views to be cached and optimize the render process. However, both of these methods are only used internally via the render method. render is the main entry point for getting the Android view representation of that asset. It automatically handles the caching and hydration optimizations, only rebuilding and rehydrating when a dependency has changed. The caller would be responsible for handling that view (i.e. injecting it into a ViewGroup).

The RenderableAsset instance is not guaranteed, meaning that state maintained within a RenderableAsset may not persist between initView and hydrate calls. If state is required, that can be accomplished by creating a custom View.

Some asset implementations may encounter a situation where the cached view is no longer the corresponding representation of the asset. Under this circumstance, the asset can request a full re-render by calling invalidateView from any point in the hydration context.

Implementing `initView`

fun initView(): View

The only goal of initView is to build an Android View. This can be done through inflation, programmatic building, or some framework, as long as the View that is returned represents the corresponding asset. Top-level view creation and any one-time configuration operations should be done in this step. It is best practice to ensure that any access of the asset model is not done in this phase, as initView is not guaranteed to be called if the data changes.

Implementing `hydrate`

fun View.hydrate()

Hydration is the process responsible for populating the view with the data from the asset model. Any dependencies on the data model should be handled in this step. This includes accessing data, transform functions, or even nested assets. Any views created in hydrate will not be automatically cached, but will persist on the UI unless explicitly removed. It is necessary to be vigilant when constructing and removing these views.

Accessing Data

In most cases, there is some additional data that is used to make the rendering more meaningful. For instance, the intent of the previous text asset example was to render a View that displayed the string contained in value. Access to such data will be provided through a data member on the DecodableAsset. This data member is a type specified when defining the subclass.

class TextAsset(assetContext: AssetContext) : DecodableAsset<TextAsset.Data>(Data.serializer()) {

    @Serializable
    data class Data(
       val value: String
    )

}

With this defined, the data can be accessed as an instance of TextAsset.Data. It’s important to note that if value isn’t defined in the content, this will cause a crash because there isn’t a default value provided. If you have optional fields, make sure the data class is structured appropriately:

@Serializable
data class Data(
   val value: String? = null
)

As a fallback, data can still be accessed via the Asset instance attached to the AssetContext. The Asset instance is a link into the underlying asset node, which provides a set of getter methods to retrieve data.

// type specific getters should throw an error if the type doesn't conform
// although, in some cases, the getter may just return null
val stringToRender: String = asset.getString("value")

Nested assets

// ...
{
    "id": "some-card",
    "type": "card",
    "title": {
        "asset": {
            "id": "some-text",
            "type": "text",
            "value": "This is a text asset"
        }
    }
}
// ...

Compound assets can be defined such that the asset model contains child assets. These child assets must be wrapped in an asset object. In the example above, there is an card asset that delegates to a text asset to render a title. The child asset can be directly described as a RenderableAsset in the data class.

@Serializable
data class Data(
   val title: RenderableAsset? = null
)

A helper is provided to reduce overhead with rendering an asset into a layout. into will show or hide the target ViewGroup based on whether the View is null.

// title_container is a view extension referencing a FrameLayout in an XML layout
data.title.render() into title_container

Styling

Styling can be done completely independently, but the API is designed such that render can accept any number of style resources. This allows parent assets to declare any styles that they’d like the child asset to use. These styles are automatically overlaid onto the current Android Context.

In the above card asset example, the card may want to set some text styles to make any text that’s rendered look like a title (i.e. bold, larger, etc).

// from the card render
// assuming that R.style.Text_Title defines these text styles
val title: View = data.title.render(R.style.Text_Title)
// the above is shorthand for:
val title: View = data.title.withStyles(R.style.Text_Title).render()

// from the text render
// create TextView with the styled context
fun initView() = TextView(context)

// ensure that the provided view is a TextView and set the text accordingly
// otherwise, invalidate the view
fun View.hydrate() {
    when (this) {
        is TextView -> text = data.value
        else -> invalidateView()
    }
}

Registering assets

Registering assets is done in the AndroidPlayerPlugin. Each plugin only needs to implement an apply method which gives the plugin the opportunity to supplement core player functionality. The AndroidPlayer instance contains an asset registry where assets should be register. A helper method has been created to make registration as simple as providing the type and a factory. The factory method must take an AssetContext, and is recommended to just be the constructor of your asset.

// registering "some-asset" with SomeAsset constructor
androidPlayer.registerAsset("some-asset", ::SomeAsset)

Partial match asset registration overrides

This allows registration of multiple assets for the same type, but can match based on other parts of the object

Consider the following asset structure with metaData:

// ...
{
    // unique identifier to distinguish between other assets in the content
    "id": "some-asset",
    // type identifier that is used to determine how to render
    "type": "action",
    // additional fields used for rendering
    "label": {...},
    // metadata
    "metaData": {
        "role": "back"
    }
}
// ...

// registering "action" with BackActionAsset constructor
val map = mapOf("type" to "action", "metaData" to mapOf("role" to "back"))
androidPlayer.assetRegistry.set(map, ::BackActionAsset)

This asset will only be used when decoding a view in the JSON tree that is type action, and has the back role. In this scenario, the custom action asset implementation would still have access to the transformed values of a regular action asset, such as the run method.

When creating a new plugin, remember to register it when building the AndroidPlayer!

Help to improve this page