@microsoft/powerappsplayersdk v0.3.0

Project

@microsoft/powerappsplayersdk

Note

• This is a preview feature.
• Preview features aren’t meant for production use and may have restricted functionality.
• These features are available before an official release so that customers can get early access and provide feedback.
• Microsoft doesn't provide support for this preview feature. Microsoft Technical Support won’t be able to help you with issues or questions.

Description

The Player SDK enables developers to:

• Embed an app by App Id
• Embed an app by Logical name, Environment Id and Tenant Id.
• Set data on the app

• Register host methods that can be called in the App.

  (Schema for the methods and data can be set using PowerApps Authoring SDK.)

• Subscribe to events from Player (like App created, App loaded and App Errored)

Installation

npm install @microsoft/powerappsplayersdk

Usage

For samples please visit: Samples

Import module into your project

import * as PowerAppPlayerSdk from "@microsoft/powerappsplayersdk";

Initialize the SDK

const sdkInitializer: PowerAppsPlayerSdk.SdkInitializer = { 
    hostName: “DemoApp” 
} 
await PowerAppsPlayerSdk.initAsync(sdkInitializer); 

Play a PowerApp by AppId

How to get AppId

If you are using @microsoft/powerappsauthoringsdk, app Id is returned in appSaved and appPublished event. Else in powerapps.com, on the Apps tab, click or tap the ellipsis(…), then Details- copy the App ID (GUID).

const options: PowerAppsPlayerSdk.PlayerOptions = { 
    externalCorrelationId: PowerAppsPlayerSdk.initializeCv(),
    parentContainerId: <ParentContainerId e.g. an Id for a div element>
}

const player: PowerAppsPlayerSdk.Player = PowerAppsPlayerSdk.Player.initPlayerByAppId(options, <appId>);
player.renderApp();

Play a PowerApp by Logical Name

How to get LogicalName, EnvironmentId, TenantId

• If using the @microsoft/powerappsauthoringsdk, these values will be returned in appSaved and appPublished events (only when the application is created within a solution).

LogicalName 1. Go to powerapps.com. 2. Click on the Solutions link in the left-hand side navigation 3. Open the solution in which the App was added or created. Copy the “Name”.

Environment Id 1. Go to powerapps.com. 2. From top-right corner select the environment in which you application exists. 3. Copy the id (GUID) after environments portion in URL.

Tenant Id 1. Go to powerapps.com. 2. Click on the Apps tab, click or tap the ellipses(...), then Details. 3. In the Web Link section, copy the GUID after 'tenantid='.

const options: PowerAppsPlayerSdk.PlayerOptions = {
    externalCorrelationId: PowerAppsPlayerSdk.initializeCv(),
    parentContainerId: <ParentContainerId e.g. an Id for a Div element>
}
const player: PowerAppsPlayerSdk.Player = PowerAppsPlayerSdk.Player.initPlayerByAppId(options, <logicalName>, <environmentId>, <tenantId>);
player.renderApp(); 

Set data on the application

The data should conform to the schema that was provided when the app was authored. For more information see 'MakerSession::setDataAsync' method on @microsoft/powerappsauthoringsdk.

public setData(data: PowerAppsData): void; 

Register a host callback

Schema for the callback is set during authoring time using the 'MakerSession::setHostMethodDefinitionAsync' method on @microsoft/powerappsauthoringsdk.

public registerHostFunction(name: string, func: Function) :void;

onAppLoaded event

Event is triggered when App is successfully loaded. The onAppLoaded event is of type EventHook. Which means when the event is raised, it has a single parameter which conforms to the PlayerInfo interface which provides the appId.

function onAppLoaded(playerInfo: PowerAppsPlayerSdk.PlayerInfo) { 
    Console.log(“User loaded an application with id: “ + playerInfo.appId); 
} 
// Subscribe to app load event 
player.onAppLoaded.subscribe(onAppLoaded);

onAppUnload event

Event is triggered when the App is closed. This can happen before load is fired. For e.g. It happens when user does not agree to consent dialog. The onAppUnload event is of type EventHook.

function onAppUnload(playerInfo: PowerAppsPlayerSdk.PlayerInfo) { 
    Console.log(“App with id: “ + playerInfo.appId + “ Unloaded”); 
} 
// Subscribe to app unload event 
player.onAppUnload.subscribe(onAppUnload);

onAppError event

Event is triggered when the App when does not load due to an error. The onAppError event is of type EventHook< PlayerInfo>.

function onAppError(playerInfo: PowerAppsPlayerSdk.PlayerInfo) { 
    Console.log(“App with id: “ + playerInfo.appId + “ errored”); 
}
// Subscribe to app error event 
player.onAppError.subscribe(onAppError);

Dispose a Player instance

This will stop the app rendering and unsubscribe from all the events.

player.dispose();

License

See the LICENSE file for details