Allow apps to update their metadata that is returned in instanceMetadata

[Roaders]

Enhancement Request

Use Case

FDC3 allows a user to open multiple instances of the same application. If you have an application that displays a stock price chart then you could have an instance that displays prices for Apple, Google and Meta. If you raise an intent and want to handle that intent in one of those applications there is currently no way of telling these 3 instances apart and they will all appear the same in the app resolver UI.

The closest that we currently have is the name and title field in the AppMetadata object. This object can be returned by the getAppMetadata function where it should obviously return data for the queried app but when returned from the findIntents or findIntentsByContext functions it would be possible to modify this object on a per instance basis. It would also be possible to modify the result from getAppMetadata to return instance specific details if an instanceId was included in the AppIdentifier - but I do no think that this would be a good idea.

There is also no defined way that an application is able to update it's title so that if a user navigates from Apple to Google within the app the Desktop Agent is able to correctly display the updated title the next time that the app resolver ui is displayed.

Questions:

• should we add a getInstanceMetadata function that would return an InstanceMetadata object? (this object may not be required, we could probably just use the AppMetadata object).
• should we define a way that applications are able to inform the desktop agent what their title is? It would currently be possible to generate a title for new instance when it is opened based on the context that is sent. For example the name of a contact or the id of a stock ticker but there is no standardized way of updating this title. It is obviously possible to do this but with no standardised way of doing it apps from different sources will not be able to do it in Desktop Agents that they do not know about.

I thought it was worth discussing this before I implement a home brew way of handling this in our own agent.

[kriswest]

Certainly an interesting topic to discuss. Having implemented several different solutions to this in Intent Resolver UIs (including both visual highlighting of app windows, title bar flashes and mini visualisations of window positions on the screen(s)), I am aware of the challenge for desktop agent implementations!

The window title is a reasonable solution where apps are displayed in windows - less so for DAs that use iframes without titles. We don't currently track the page title in the agent-proxy/DACP (to send back to desktop agent) but its a thing we could do...

findInstances only returns AppIdentifier, but it would be nice for any solution to also cover that. We could upgrade that to return an AppMetadata[] (if that gets new fields) as it extends AppIdentifier.

[kriswest]

We discussed tracking document.title at #1856 to trigger the message to the DA automatically, with a getAgent argument to disable + a manual API call as an alternitve (using the same DACP messages)

[Roaders]

As @kriswest mentioned the default way for the instance title to be updated would be through modification of document.title. The DesktopAgentProxy would listen to events and whne changed would send a message to the DA informing it of the change.

We will add new parameters to the getAgent call that will allow this mechanism to be disabled.

A new function updateInstanceTitle() (unless anyone has a better suggestion) will be added to the DesktopAgent interface to allow the title to be updated via the agent rather than modifying the document title.

To get the title for display we will modify the AppMetadata title field to reflect the title of the instance IF the metadata has an instanceId. This change will be reflected in the getAppMetadata() call and in the returned metadata in the findIntent and findIntentsByContext results for app instances.

We will also modify the result of the findInstances call to return AppMetadata rather than AppIdentifier. One extends the other so this will not be a breaking change.

[Roaders]

We discussed a new api call: updateInstanceTitle on #1856 and at the time we couldn't think of any other fields that we might want to update on an instances AppMetadata record.
I have now thought of one!
In our implementation it would be useful for an app instance to update it's version at runtime. We also have the instanceMetadata field that we would definitely want to be able to update on a per instance basis.

Perhaps we just need an updateInstanceMetadata(metadata: AppMetadata) function rather than the title. The matadata object that's provided would replace the one currently held by the DesktopAgent.

This leads to a couple of new questions:

• Do we allow partial updating? i.e. if I send {appId: "whatever", instanceId: "whatever", title: "My New InstanceTitle"} does this delete all the other fields held by the Desktop Agent? Do we just merge the above with the data currently held?
• Are there any fields that should not be updateable at runtime?

[kriswest]

Are there any fields that should not be updateable at runtime?

Looking at AppMetadata i think we might be better to establish typing for the instanceMetadata element (InstanceMetadata) and only allow updates using that... That way we can retain the app title field as it appears in the IntentResolver for a new instance/appD and instead have an updateable instanceMetadata.title field, making the update API call the more intuitive:

updateInstanceMetadata(metadata: InstanceMetadata)

which can just overwrite the existing object?

To do an update (without knowing the full object already) would then be:

const instanceMeta = (await fdc3.getInfo()).appMetadata.instanceMetadata;
instanceMetadata.title = "new title"
await fdc3.updateInstanceMetadata(instanceMeta);

[Roaders]

This issue was discussed at #1865 and there were no objections so what we have tentatively agreed to is:

• create a new interface: InstanceMetadata. This will repalce the current type used by instanceMetadata within the AppMetadata object. At the moment this will have title and an index signature to allow it to be extended
• Add a new function to the DesktopAgent interface:
  updateInstanceMetadata(metadata: InstanceMetadata)
• update the findInstances function to return AppMetadata (with a populated instanceMetadata property)
• ensure that the AppMetadata objects returned from the findIntents and findIntentsByContext functions include the instance metadata
• update DesktopAgentProxy to invoke the updateInstanceMetadata function when the document title is updated
• add a new getAgent() property to disable this functionality that will be turned on by default