Beacon Plugin

The beacon plugin enables users to send and/or collect beaconing information from assets in a normalized API. It exposes a common API for publishing beacons from an asset library, and will automatically attach itself to the current view, enabling additional meta-data to be added to each event.

Consuming Beacons

Beacon Format

By default, the beacon plugin returns beacons in the following format:

interface DefaultBeacon {
  /** The user action taken ('clicked', 'visited') **/
  action: string; 

  /** The type of UI element interacted with ('button', 'menu') **/
  element: string;

  /** Any additional data from a `metaData.beacon` property **/
  data: any;

  /** The id of the asset **/
  assetId: string;

  /** The id of the view **/
  viewId: string;
}

Usage

Add the beacon plugin to a player:

import { Player } from '@player-ui/player';
import { BeaconPlugin } from '@player-ui/beacon-plugin';

const player = new Player({
  plugins: [
    new BeaconPlugin({

      // Any plugins to the beacon-plugin
      plugins: [],

      // Callback to handle any beacon event
      callback: () => {}
    }),
  ],
});

Beacons can be published directly by the plugin, but in most cases, a platform specific adapter is recommended.

beaconPlugin.beacon({
  action: 'click',
  element: 'button',
  asset: asset // The entire Asset object, for use in the plugin pipeline
  // other metadata
});

Just like with the core variant, to add support for beaconing in the react player, add the plugin to Player:

import { ReactPlayer } from '@player-ui/react';
import { BeaconPlugin } from '@player-ui/beacon-plugin-react';

const player = new ReactPlayer({
  plugins: [
    new BeaconPlugin({

      // Any plugins to the beacon-plugin
      plugins: [],

      // Callback to handle any beacon event
      callback: () => {}
    }),
  ],
});

This will add additional React Context to the running player for the producers from asset-libraries to leverage.

CocoaPods

Add the subspec to your Podfile

pod 'PlayerUI/BeaconPlugin'

Swift Usage

To receive Beacon events from Player in iOS, add the BeaconPlugin to your plugin array:

var body: some View {
  SwiftUIPlayer(
    flow: flow,
    plugins: [
      BeaconPlugin<DefaultBeacon> { (beacon: DefaultBeacon) in
                // Process beacon into the format you need for your analytics platform
            }
    ]
  )
}

If you are modifying the beacon using core BeaconPlugin plugins:

struct CustomBeacon: Decodable {
  public var action: String
  public var element: String
  public var customElement: Int
}

class CustomBeaconPlugin: JSBasePlugin {
  convenience init() {
    self.init(fileName: "custom-beacon", pluginName: "CustomBeaconPlugin")
  }
  override open func getUrlForFile(fileName: String) -> URL? {
        ResourceUtilities.urlForFile(
          name: fileName,
          ext: "js",
          bundle: Bundle(for: <YourMainPodClass>.self),
          pathComponent: "<YourResourceBundleName>.bundle"
        )
    }
}

// In some SwiftUI View
var body: some View {
  SwiftUIPlayer(
    flow: flow,
    plugins: [
      BeaconPlugin<CustomBeacon> { (beacon: CustomBeacon) in
                // Process beacon into the format you need for Segment/Trinity and send it on
            }
    ]
  )
}

Beaconing on the JVM platform (including Android) is done with an instance of the BeaconPlugin. By default, the Android Player includes a wrapper of the core beacon plugin. The Android Player can be configured to override the default BeaconPlugin by passing a different BeaconPlugin implementation on instantiation which can contain further configuration.

Without additional configuration, the BeaconPlugin doesn’t provide much value. Beacons must be explicitly handled in order to forward them to an analytics platform (segment, Trinity, etc.). This is done by calling registerHandler(handler: (String) -> Unit) with a callback.

val beaconPlugin = BeaconPlugin()
beaconPlugin.registerHandler { beacon: String ->
    // Process beacon and send to analytics platform
}

There may be some beacons that are fired automatically by the BeaconPlugin implementation, but in most cases, there are additional beacons that should be fired on some interaction (i.e. user tapping button asset). This is done by calling beacon(action: String, element: String, asset: Asset, data: Any? = null) with the relevant information.

val beaconPlugin = BeaconPlugin()
beaconPlugin.beacon(
    "clicked",
    "button",
    assetThatIsBeaconing,
    someData,
)

For convenience, there are several extension methods for utilizing a pre-installed BeaconPlugin from Player. If there isn’t a BeaconPlugin installed, Player will produce a warning log.

// registering handler
androidPlayer.onBeacon { beacon: String ->
    // Process beacon and send to analytics platform
}

// fire beacon
androidPlayer.beacon(
    "clicked",
    "button",
    assetThatIsBeaconing,
    someData,
)

The base RenderableAsset class provides an additional helper to make beaconing less verbose from an asset perspective.

Helper in RenderableAsset

Beacon Plugins

Similar to how Player accepts plugins, the beacon-plugin itself accepts a list of plugins. These are able to mutate and augment the beacon payload as it makes its way through the publishing pipeline.

There are 3 hooks that are currently exposed:

buildBeacon - Assembles a given beacon ffor publishing
cancelBeacon - Given a current beacon, determine if it should be published or not.
publishBeacon - Receive the final becaon. This is a substitute for the callback in the beacon plugin options.

Publishing Beacons

beacon expression

The beacon plugin adds support for a beacon expression that can be referenced within content. Each beacon referenced from this expression will be assumed to originate from a view (no local asset information will be attached)

{
  "asset": {
    "id": "my-action",
    "type": "action",
    "exp": "beacon('my-action', 'some-data')"
  }
}

Assets

useBeacon hook

The @player-ui/beacon-plugin-react package exports a hook that assets can leverage to publish beacons.

The useBeacon hook takes base options that apply broadly, and returns a function with those options as the base. You can then pass event specific information when calling beacon.

Example

import { useBeacon } from '@player-ui/beacon-plugin-react';

// inside of your asset
export const Component = (props) => {
  const beacon = useBeacon({ action: 'clicked', asset: props });

  return (
    <button
      onClick={() =>
        beacon({
          element: 'button',
          data: {
            custom: 'fields',
          },
        })
      }
    >
      Click Me
    </button>
  );
};

The SwiftUIBeaconPlugin attaches a BeaconContext to the root of the SwiftUI view tree as an environment value, so when included any asset can use that context to send a beacon, if the context is in the environment:

struct ActionAssetView: View {
  @ObservedObject var viewModel: AssetViewModel<ActionData>
  @Environment(\.beaconContext) var beaconContext: // implicitly typed as -> BeaconContext?
  var body: some View {
    Button(action: {beaconContext?.beacon(action: "clicked", element: "button", id: model.data.id)}, label : {...})
  }
}

Using the base RenderableAsset’s helper function in this example fires off a basic beacon with no adjustment to format as well as empty data upon button click

Example

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

    @Serializable
    data class Data(
      ...
    ) : AssetData()

    override fun createView(): View {
      ...
    }

    override fun View.hydrate() {
        val binding = MyCustomViewBinding.bind(this)
        binding.button.setOnClickListener {
          this@MyAsset.beacon(
            action = BeaconAction.clicked,
            element = BeaconElement.button,
            asset = this@MyAsset,
            data = null
          )
        }
        ...
    }
}

Help to improve this page