Connectifi.DesktopAgent 0.0.5-beta.1

Connectifi.DesktopAgent.NET

This library provides a wrapper around the web Connectifi Agent, exposing an FDC3 API in .NET.

Usage

Create an instance of the DesktopAgent

var desktopAgent = new DesktopAgent(webView2.CoreWebView2);

The WebView2 parameter is used to proxy API calls to the web implementation of the Connectifi Desktop Agent. It should be set to a URL !! Add URL EXAMPLE !!

Typically it should be hidden from the user by default and only shown if the desktopAgent.OnWebVisibility event requests it to visible. This occurs when the user is to manually input authentication credentials.

Note: DesktopAgent must created on the UI thread related to the provided WebView2.

DesktopAgent Events

OnConnectifiEvent

This event occurs whenever the web agent received any event from Connectifi. It can be type converted to any of the following possibilities. Please see the Web documentation for further information.

• HandleOpenConnectifiEvent
  Called after fdc3.open or an intent is resolved. In this case, the service sends a message to the client requesting it to launch a specific app. The message format is as follows:

class ConnectifiOpenMessage
{
    string Name { get; }
    pstring Url { get;  }
}

Where name is the name of the app in the directory, url is the url to launch (for web applications)
By default it opens the default web browser at the provided url.
See more

• OnAuthErrorConnectifiEvent
  Called when the user could not connect to the directory because they could not be authenticated. Passed the directory name as an argument.
• OnSessionErrorConnectifiEvent
  (Deprecated) Called when the user could not connect to the directory because the app was not registered in the directory or the directory could not be found. Passed the directory name as an argument.
• OnAppIdentityErrorConnectifiEvent
  (Deprecated) Called when the user could not connect to the directory because the app was not registered in the directory or the directory could not be found. Passed the directory name as an argument.
• OnLoadErrorConnectifiEvent
  Called when the there is a timeout connecting to the service (interop endpoint).
• OnChannelJoinedConnectifiEvent
  Called when a channel is joined. Argument is the id of the channel joined.
• OnChannelLeftConnectifiEvent
  Called when leaveCurrentChannel is executed. I.e. the user leaves the current channel but does not join another.
• OnConnectedConnectifiEvent
  Called when a socket connection is established.
• OnDisconnectedConnectifiEvent
  Called when the socket connection is dropped. Will be passed the auto-reconnect time (in milliseconds) as an argument.
• OnWorkingChangedConnectifiEvent
  Called when the agent starts or stops "working" or "being busy". the boolean argument is the current state.
• OnSignedInConnectifiEvent
  Called after the user has successfully signed into the directory. Will be passed the username / identifier as an argument.
• OnSignedOutConnectifiEvent
  Called after the user is signed out.

desktopAgent.OnConnectifiEvent += (s, e) =>
{
    if (e.ConnectifiEvent is OnConnectedConnectifiEvent)
    {
        //
    }
};

OnHandleIntentResolution

This event is to trigger showing the user a list of options for handling an intent and then providing back their chosen selection.

desktopAgent.OnHandleIntentResolution += (s, e) =>
{
    // show user the choice of apps from the available list within e.HandleIntentResolution.Message
    // after user selection call
    // e.HandleIntentResolution.Callback(/* selected app */, /* selected intent */);
};

class HandleIntentResolution
{
    IntentResolutionMessage Message { get; }
    Task Callback(ConnectifiApp selected, string intent);
    Task CloseCallback(bool? resolve);
}

The intent resolution message has the following properties:

 class IntentResolutionMessage
{
    ResolutionType ResolutionType { get; }  // �intent-resolver� or �context-resolver� depending on if the resolution is coming from a raiseIntent or raiseIntentsForContext call.
    T? Context<T>() where T : IContext;     // the FDC3 context object associated with the intent - you must specify the generic argument as the type to deserialize to - e.g. Instrument
    AppIntentResult[] Data { get; }         // either a single result (�intent-resolver� type) or a list of results (�context-resolver�). See AppIntentResult below.
}

class AppIntentResult
{
    IntentMetadata Intent { get; }
    ConnectifiApp[] Apps { get; }
}

class ConnectifiApp : AppMetadata
{
    string Type { get; }
    string Id { get; }
    string Url { get; }
    string InstanceTitle { get; }
    DirectoryIntent[] Intents { get; }
    int Proximity { get; }      // Starting with 0 - a number indicating the relative device and application proximity from the app that initiated the resolver. For example, if the target app is on the same device and running in the same application (e.g. Chrome) as the initiator, proximity is 0. The scoring is meant to aid sorting the list in order of apps closest to furthers from where the user is currently working.
    string Useragent { get; }   // the raw user agent string for the app
    string Browser { get; }    // indicator of browser type the app is running in
    string Device { get; }     // indicator of the device the app is running on
    string Os { get; }         // indicator of the OS the app is running on
    long LastUpdate { get; }
}

The AppIntentResult joins up the standard FDC3 IntentMetadata type with an Array of ConnectifiApp types. (i.e. an intent and the app results matching it). The ConnectifiApp type is an extension of the standard FDC3 AppMetadata type that provides some additional properties that be used to help the user disambiguate between applications.

OnAuthRequired

DesktopAgent will send an OnAuthRequired event to inform the container that authorization is required, in which case the App should show the necessary web view. The DesktopAgentWPF class will handle the web view display itself.

desktopAgent.OnAuthRequired += (s, e) =>
{
    jsWebview.Visibility = e.IsAuthRequired ? Visibility.Visible : Visibility.Collapsed;
};

Configuration

The DesktopAgent can be configured to disable default behaviors through the Configuration property.

desktopAgent.Configuration.DefaultHandleOpen = false;      // disable opening default web browser at app url when HandleOpenConnectifiEvent is received
desktopAgent.Configuration.DefaultHandleAuthError = false; // disable navigating to login screen within WebView2 for manual user authentication when OnAuthErrorConnectifiEvent is received

Dependencies

• Json.NET
• Microsoft WebView2
• fdc3-dotnet

References

• Connectifi Agent Web

License

Copyright 2024 Connectifi

Distributed under the Apache License, Version 2.0.

SPDX-License-Identifier: Apache-2.0