Reference13r1:Concept myApps platform services

From innovaphone wiki
Revision as of 08:58, 1 April 2022 by Kpe (talk | contribs) (→‎Codecs)
Jump to navigation Jump to search
There are also other versions of this article available: Reference13r1 (this version) | Reference13r2 | Reference13r3 | Reference14r1

myApps platform services provide various operating system specific services which can be used by other Apps running in the myApps client. Those services typically are not available in the browser's JavaScript environment and hence must be implemented in native platform code. Therefore, the platform services are installed as native executable on the respective platform.

When myApps is started in a web browser (and hence has no access to the platform services), some Apps will use WebRTC services implemented by the browser instead. For ease of reference, features available in this scenario are also described here.

On windows, the platform services also come with their own web browser in which the myApps web App will be started then. This browser is based on google's Chromium open source software.

Applies To

  • myApps
  • myApps for Windows
  • myApps for iOS
  • myApps for Android
  • myApps Web App (WebRTC)

version 13r1

Features

Not all features are available or required on all platforms.

Feature Description Availability
Windows iOS Android Browser[1]
audio manage local audio devices to record and playback audio conversations ✔ (audio available but devices managed by web browser)
video manage local displays and cameras to capture and render video live stream ✔ (video available but devices managed by web browser)
ringer manage local ringing device
application sharing
  presenter share an application
  consumer view an application shared be the peer
  control take control of presenters application (mouse & keyboard)
hot keys capture key presses for quick invocation of phone apps (e.g. dial selected number)
tel: and sip: URI handler intercept clicks on tel: and sip: links in web sites to invoke phone apps ? ?
user activity set presence state according to user activity ? ? [2]
docking myApps can be docked persistently to the right or left edge of your screens
multi-windowing Apps can be launched in separate windows
notifications display notifications with OS standard mechanism ✗? ✗? ✗?
phone book access access local phone book
office presence provider maps PBX presence state to Microsoft office presence state


external application start start arbitrary external applications for calls
push wake-up app from background mode on event (e.g. incoming call)
app proxy a caching proxy that provides app persistence
auto update automatically updates myApps platform services to the same version the PBX has [3]
three party conference initiate 3-pty-conference using Softphone-App
exclude VPN disable use of VPN connections for audio/video/appsharing
  1. This refers to the myApps web application running in a browser with no platform services available
  2. limited, see User activity below
  3. The then-current web app is always loaded from the PBX upon startup and hence up-to-date by definition

Requirements

  • innovaphone PBX 13r1 and up


myApps for Windows

  • Windows 10
  • Windows Server 2016 and later versions

32 & 64 bit Windows

  • 32 bit Windows: install the myAppsSetup32.msi from the App Store
  • 64 bit Windows: install the myAppsSetup.msi from the App Store
    • the 64 bit variant still installs into Program Files (x86), as the main myApps.exe is still a 32bit application
    • the 64 bit variant just contains an additional 64 bit binary for the outlook search

Windows N editions

Windows N editions are missing the Media Feature Pack which is pre installed on other Windows versions.

Please install the pack from Microsoft (Windows 10 pack) before you install myApps. The installer will check if the file C:\Windows\SysWOW64\mfplat.dll exist on your system.

Make sure to install the correct pack depending on your Windows version! There are different packs for Windows 10 1703, 1803, 1809 and 32bit or 64bit etc.

NB: Sometimes the myApps installation will not work even though the media pack is already installed. This is because the installer has no read access to check if the package is already installed. If the above-mentioned file exists and the installer asks to install the Windows Media Feature Pack nevertheless, you have to start the myApps install with administrative rights.

myApps for iOS

  • iOS 12 or higher

myApps for Android

  • Android 6.0 or higher. Android 6.x may need an update of the Chrome browser.

Licenses

  • No license needed for myApps platform services

Overview

myApps platform services is a native executable that is installed using the standard mechanisms on the respective operating system. It provides various advanced services which can be used by the myApps web client code as well as the Apps running in the myApps context.

Also, on Windows, the platform services come with their own, dedicated browser to run myApps in. This browser is based on Chromium. On iOS and Android it's based on native embedded web view facilities instead.

Components

RTP service for audio, video and data

The RTP service provides audio, video and data (app sharing) VoIP RTP endpoints (e.g. for softphones). It supports STUN, TURN, ICE, SRTP, DTLS. Note however that unlike WebRTC, these endpoints do not require ICE and DTLS. In other words, they can communicate also with non-compliant (i.e. older) VoIP devices.

Note that the available capabilities when not running the myApps platform services depend on the used browser's WebRTC implementation. See your browser documentation for details.

Apps can request RTP channels using the Media Protocol's AllocChannel message.

RTP ports
audio 50000 -> 50099
video 50100 -> 50199
data 50200 -> 50299


The RTP service will enumerate all local interfaces and create local HOST candidates for ICE. There is an option however to disregard VPN interfaces (more precisely such interfaces with type of IF_TYPE_PPP or IF_TYPE_TUNNEL). This can eliminate quality issues when RTP data is transmitted through TCP based VPN tunnels.

SRFLX and RELAY candidates are obtained using the STUN and TURN server configuration passed by the App (e.g the softphone App) as part of the AllocChannel request. {"mt":"AllocChannel","channel":"81429cba-396d-43de-8a76-ec020ba8796e","iceServers":[{"urls":"turn:myturn.domaincom:3478?transport=udp","username":"turnuser","credential":"pwd","credentialType":"password"},{"urls":"stun:mystun.domain.com:3478"}],"dn":"Foo Bar","type":"RemoteRtp","kind":"video"}

Codecs

The installed myApps launchers provide codecs that can be used by softphone apps for media streams. When running in a web browser the codecs depend on the browser version and operating system. See the documentation of your browser for details.

The following codecs are supported:

Codec Windows-Launcher Android iOS Firefox (Browser) Chrome (Browser) Edge (Browser) Safari (Browser) Opera (Browser)
Audio
G711A
G711u
G722
G729 X X X X X
G729A X X X X X
G729B X X X X X
G729AB X X X X X
OPUS-NB X
OPUS-WB X
Video
VP8 X
VP9 X
H264 X X
Application Sharing
Share X X X X X X X
Watch ✔* ✔* X

* small presentation only

Video capture

The default resolution for video capture is 352x288 if available. Otherwise, 320x240 is used. The frame rate is 30 fps if available, otherwise 15 fps is used. The resulting average bandwidth will be 350 kbps.

Application sharing

Screen content and mouse position will be transmitted by the presenter. Mouse and keyboard control can be handed over to viewers. Bitrate is restricted to 500 kbps.

Device handling

The RTP service enumerates microphones, loudspeaker, cameras and ringing devices and notifies apps when devices come and go. It is up to the apps using the devices to store preferences.

In the Windows Launcher the RTP service also enables some extended features (such as hook switch or volume control) for supported USB headsets or Bluetooth headsets connected to myApps.

For this to work, vendor specific development kits from Jabra, Epos (formerly Sennheiser) and Poly (formerly Plantronics) are integrated.

Note that it is possible to inhibit the start of the Sennheiser SDK (SenncomSDK.exe) using the DISABLEHEADSETS directive of the installer (see MSI parameters below). The supported headset-SDKs determine which headset vendors are recommended to be used with the myApps softphone app.

Ring tones

Ring tones can be played. Apps can choose the tone from a pre-defined list of ring tones.

On Windows, custom ring tones can be uploaded as .mp3 files to the ringtones sub-directory of myApps' install directory (which usually is in C:\Program Files (x86)\innovaphone\myApps).

Debugging

For extended debugging, turn on the Audio, Media and AppSharing traces in myApps.

Hot keys

On Windows systems, myApps platform services can listen for hot keys and invoke certain functions. Invocation is done by sending API messages to myApps which passes it to an appropriate API provider (in the cases described here, this will be a phone or softphone or rcc App typically. See Client APIs and default apps for more details about this mechanism.

The hot keys can be specified using the advanced settings user interface (see UI elements below. Any of the function keys F1 to F11 (optionally combined with up to two modifier keys alt, ctrl, shift or win) can be chosen for each function.

dial selected number
Initiates a call using the currently selected text as target.
A PrepareCall message with the text argument set to the selected text and the adjust argument set to true will be sent to the com.innovaphone.phone API.
{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":"mt":"PrepareCall","text":"13","adjust":true}}
accept call
Accepts a currently alerting call.
A ConnectCall message will be sent to the com.innovaphone.phone API.
{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"ConnectCall"}}
reject/disconnect call
Rejects a currently alerting call or disconnects an active call.
A DisconnectCall message will be sent to the com.innovaphone.phone API.
{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"DisconnectCall"}}

URL Handler

On Windows systems, two URI-handler are installed with the myApps platform services. Windows will call up this URI handler when a user clicks on an appropriate link, for example in a web site.

The handler will the send an API message to myApps which passes it to an appropriate API provider (in the cases described here, this will be a phone or softphone or rcc App typically. See Client APIs and default apps for more details about this mechanism.

tel URI
call a number, e.g. tel:4711
A PrepareCall message with the num argument set to the selected text and the adjust argument set to true will be sent to the com.innovaphone.phone API.
{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","num":"4711","adjust":true}}
sip URI
call a SIP name, e.g. sip:zkl@innovaphone.com
A PrepareCall message with the sip argument set to the selected text and the adjust argument set to true will be sent to the com.innovaphone.phone API.
{"mt":"ApiRequest","apiId":"com.innovaphone.phone","consumer":"@local-ae2fc2ab74-3f1e-4ab9-b215-d42f213520317","msg":{"mt":"StartCall","sip":"zkl@innovaphone.com","adjust":true}}

User activity

On Windows systems, the myApps platform services can monitor user keyboard/mouse activity and change the user's presence state after a certain amount of inactivity. The timeout can be specified using the advanced settings user interface (see UI elements below.

myApps will then send a SetUserActivity message to the PBX using the myApps protocol.

{"mt":"SetUserActivity","inactive":true}

This will change the status property of the im: contact for the user's own presence and hence result in a presence update from the PBX to myApps

{"mt":"UpdateOwnPresence","presence":[{...},{"contact":"im:","activity":"","status":"closed"}]}

The closed status is reflected in the grey status color when displaying a contact Myapps-inactive.png.

On iOS and Android, the state is set to inactive as soon as the App is brought to background. When myApps platform services are not available (i.e. when running the web application in a browser solely) a limited user activity monitoring is available: the state is set to active when the web page is not used for more than 5 minutes.

Notifications

The myApps platform services can use the OS specific notification mechanism (e.g. desktop notifications on Windows) to display messages (e.g. incoming new chat message) to the user.

Note that the actual rendering of the notification is under control of the OS. Therefore, myApps must be allowed to show notifications and its appearance can be restricted by OS native settings.

Windows

If notifications do not work, please check:

  • Shortcut. During myApps installation a shortcut must be created in C:\ProgramData\Microsoft\Windows\Start Menu\Programs\innovaphone\myApps for the notifications to work. Please check that this shortcut is present.
  • Windows Settings. Check following screenshots:

Notifications0.jpg Notifications1.jpg

Local phonebook access

The myApps platform services implement an API provider for the com.innovaphone.search API]. They perform search capabilities on the OS' local phone books which can be used by Apps like the phoneapp.

Apps would send a Search request to the API:

{"mt":"ApiRequest","consumer":"dev:SwPh_zkl_5e42e884","provider":"*","src":"4","msg":{"mt":"Search","type":"contact","search":"john doe"},"apiId":"com.innovaphone.search"}

Search results are delivered as SearchInfo messages:

{"mt":"ApiResult","src":"3","provider":"@local-8125d22e37-519d-4056-bfe5-c52ef2ae8fabb0","consumer":"dev:SwPh_zkl_5e42e884","client":"@client-f62702dd86-be3f-47fc-b4bc-7a21627b75b2ea","msg":{"mt":"SearchInfo","relevance":2000,"adjust":true,"type":"contact","contact":{"givenname":"John","sn":"Doe","company":"ACME","position":"Head of everything","telephonenumber":["11111","22222"],"homephone":["+4944444","33333"],"mobile":["+49 (123) 55555"]}},"api":"com.innovaphone.search"}

Note that Apps never perform a reverse (number) lookup, neither is there an API defined for it. This is done centrally within the PBX. However, as the PBX has no access to the user's local phone books, entries therein are not searched for reverse lookup.

Windows

On Windows, the search is performed in all of the user's Outlook contact folders. As opposed to the search implemented in the Contacts and Users App, all items are returned which match any of the search words (i.e. searching for a b will return items matching either a or b).

searched properties
fistname, lastname
returned properties
Following Outlook contact phone number properties are returned (if available):
  • OFFICE_TELEPHONE_NUMBER as telephonenumber
  • OFFICE2_TELEPHONE_NUMBER as telephonenumber
  • HOME_TELEPHONE_NUMBER as homephone
  • HOME2_TELEPHONE_NUMBER as homephone
  • MOBILE_TELEPHONE_NUMBER as mobile
  • BUSINESS_FAX_NUMBER as facsimiletelephonenumber

Note that contact information is cached in the search provider. Updated contacts may therefore become effective after a while only. Outlook search will create its own trace file myAppsOutlookSearch-date-time.txt in the standard trace directory.

This search provider is always installed and active and cannot be disabled. There is no need (nor possibility) to enable it in the Apps tab of the PBX's user object. Also, no App object needs to be created for it.

Microsoft Office integration

The myApps platform services has a office presence provider that can provide the user's presence state to Office applications. See myApps Office Integration for details.

This feature is installed by default. However, it can be disabled using the OFFICEPRESENCE MSI Parameter. Also, a check-mark is available in the setup dialog.

Call an external application for calls

Phone Apps (such as the phoneapp or softphone) can initiate the start of an external application when a new call appears (either incoming or outgoing). The actual spawning of the application is done by the myApps platform service. Also, the application properties (such as e.g. the executable's path) is configured in the myApps platform services (see Advanced settings in the UI elements section below).

A number of arguments can be passed to the application by substituting $-variables in the Parameter field:

$n
phone number as dialed (called party number for outgoing calls) or received (calling party number for incoming calls)
$N
called or calling party number in national format (e.g. 07031730090)
$I
called or calling party number in international format (e.g. +497031730090)
note that both $N and $I only work if $n includes both subscriber number and area code (e.g. 07031730090). Otherwise they are equal to $n
$d
display name of peer (if known)
$c
conference id
this is a globally unique ID for this call and may be used to relate the call to the guid found in the CallInfo structure in the SOAP-API and RCC-API . Also, corresponding CDRs can be related using the event tag's conf attribute.

The start of an external application can be requested using the com.innovaphone.externalapps API.

Push

Mobile operating systems usually inhibit network operation of apps which run in the background or are closed by the user. This is done in order to reduce battery consumption. Unfortunately, this also stops such apps to maintain a registration by regularly sending keep alive messages to a server (in our case to the PBX). As a result, myApps will be disconnected from the PBX. When the PBX determines that there is an event for the application which needs a response, it needs to wake up the app using a dedicated channel provided by the operating system. This mechanism is know as push. When running on iOS or Android, myApps supports push.

For push to work, a push object needs to be configured in the PBX . Also, it needs to be enabled on the mobile phone for the myApps app. This mechanism is quite similar in v12 and v13, so you can refer to Reference12r2:Concept Push Notifications for myPBX iOS and Android for more details.

Also, helpful hints can be found in Howto:Troubleshoot v13 Push with myApps for Android and iOS.

App Proxy

myApps runs further Apps (such as e.g. the phoneapp) as a web page in an IFRAME of the browser myApps is running in. The App's page code is loaded either from the PBX or from an application platform (AP). This however would mean that the App's IFRAME would remain empty (a dead white screen) when the PBX or AP is not available. To make sure the App can start-up anyway, the myApps platform services feature the so-called App Proxy. This is a caching proxy that caches all the App code so it is available even in case of network failure. When myApps runs in the context of the platform services, Apps are therefore not loaded from the App source directly, but from the local App proxy.

The cached files are stored in the PCs local file system in the C:\Users\...\AppData\Local\innovaphone\myApps\appproxy</path>. There is no configuration required. However, if myApps seems to run with outdated or corrupt cached copies of the App, you can safely delete the entire directory.

Auto update

On Windows, the myApps platform services can auto-update themselves to a common version. This is controlled by the Launcher Software Update settings under PBX/Config/myApps in the PBX.

When myApps is started or the user logs in or myApps needs to re-connect to the PBX, the platform services will use the com.innovaphone.client API to learn the desired version (launcherUpdateBuild, which is part of the API's model). If this differs from the current version, the platform services will try to download the respective new version.

{
   "mt": "ApiUpdate",
   "apis": {
       "com.innovaphone.client": {
           "@client": {
               "title": "innovaphone myApps",
               "model": {
                   "launcher": true,
                   "launcherUpdateBuild": "134906",
                   "appStoreUrl": "http://store.innovaphone.com/release/download/"
               }
           }
       }
   }
}

The installation of the downloaded version is done by the innovaphonemyAppsUpdateService. This service is installed and enabled during the initial install of the myApps platform services. To disable auto-update, either leave the Launcher Software Update settings empty or set the service's start mode to disabled in the Windows services control panel.

Note that the update service does not work on terminal servers. Administrators must do myApps base services updates using standard windows mechanisms.

The Devices app can not update software installed on Windows PCs directly. However, when the PBX is updated using an update job in the Devices App, the Launcher Software Update settings will be updated accordingly and hence the myApps base services will ultimately also be update to the same version.

UI elements

There are a few user interfaces provided by the platform services:

tray-icon (Windows only)

Myapps-tray.png
Allows to
  • terminate myApps
  • toggle the autostart state
  • toggle the show in task bar state
  • open the trace folder

PBX connect form

Myapps-connect.png
Allows the user to specify the connect data for the PBX (i.e. IP address or DNS name)

Advanced settings

Myapps-settings0.png
Myapps-settings.png Myapps-settings2.png Myapps-settings3.png
Allows to modify various platform dependant settings (such as e.g. the hotkey selection on Windows)

Interfaces

Provided APIs

com.innovaphone.search
access to local phone book entries by the Local phonebook access component.
com.innovaphone.launcher
display of OS specific user notifications and receipt of related user actions
com.innovaphone.notificationhandler
???
com.innovaphone.externalapps
to start external applications, see Call an external application for calls above
com.innovaphone.callkit
???

Used APIs

com.innovaphone.phone
used to initiate new or manipulate existing calls by the Hot keys and URL handler components.
com.innovaphone.client
the model is used to learn the update settings, see Auto update above

Protocols

Media Protocol
used by apps to allocate RTP channels, see RTP service for audio, video and data above

Related App Services

none

Known limitations

Button on Bluetooth headsets not functional on myApps for iOS
The button of Bluetooth headsets doesn't provide to accept or disconnect calls. The button on wired earphones does.
Incoming call as banner on myApps for iOS
Since iOS 14 the iOS CallKit presents incoming calls as a banner leaving the original green answer button of myApps visible. Use only the blue button of the banner to accept the call or change iPhone Settings, App "Phone", "Incoming Calls" to "Full Screen" to hide the myApps user interface again during call answering.

Installation

Windows

myApps platform services are installed on Windows using the .msi file found in the myApps Windows package from store.innovaphone.com.

myApps can update itself automatically, see Auto update above.

MSI Parameters and install options

The MSI installer of myApps for Windows supports the following parameters and can be edited with Microsoft Orca. You can add your parameters in the table property.

SERVER
the PBX's dns server name
OFFICEPRESENCE
false to disable presence integration in Microsoft Office
this is also available as a check-mark when running the install manually
DISABLEHEADSETS
true to disable headsets support, see Device handling above
EXTERNALAPPS
pre-define external applications, see Call an external application for calls above
e.g. "{\"externalApps\":[{\"id\":1,\"name\":\"Wireshark\",\"path\":\"C:\\Program Files\\Wireshark\\wireshark.exe\",\"param\":\"\",\"autostart\":true]}"
FORCERESTART
true (or any string ...) kills myApps during the installation and restarts it for the currently logged in user, if it was running
DISABLELOCALHOST
true to disable use of localhost string to access the local webserver. Use 127.0.0.1 instead

Current settings are stored in the registry at Computer\HKEY_CURRENT_USER\Software\innovaphone\myApps or at Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\innovaphone\myApps

iOS

myApps platform services are installed on iOS by loading innovaphone myApps from the App Store.

Android

myApps platform services are installed on Android by loading innovaphone myApps from the Play Store.

Configuration

When myApps runs under the myApps platform services, it will show various platform specific settings as part of its burger menu, so the user can set them. See Advanced settings in UI elements above.

Some options can also be set globally for all myApps clients in the PBX's PBX/Config/myApps Client Settings

Option Description Where to set Availability
User menu PBX Client Settings Windows iOS Android
Autostart Launch myApps on login
Appear offline after controls after which idle time a user is considered inactive. See User activity above
Hotkeys Hotkeys for call dial, accept, reject. See Hot keys above
Docking Docking mode (left, right, none). See ?? above
Desktop notifications Turn on/off platform notifications. See Notifications above ✗? ✗?
VPN Disable VPN address for ICE candidate selection. See RTP ports above
Show in taskbar Show myApps in the taskbar in addition to it's tray icon.
Log flags turn on/off certain trace levels. See Troubleshooting below.
External applications define the applications available for Apps to be started. See Call an external application for calls above.
Ring in headset send ring tone for incoming to headset instead of loudspeaker (should be in phoneapp rather???)

Start parameters for Windows

On Windows, it is not possible to pass start parameters from the Chromium documentation to the myApps process.

OS Settings for Windows

Windows settings can influence the display of Desktop notifications. See Change notification settings in Windows 10 for details.

OS settings for Android

Events
???
Call accounts
???
Background data, unlimited data usage
???
Overlaying
???

OS settings for iOS

Notifications
???

Troubleshooting

myApps platform services can write various traces for debugging. Trace can be turned on and off selectively in the Advanced settings.

The following trace flags can be set:

Abbreviation code description
App 0x000000001 logs from the App Service itself
DNS 0x000000008 logs DNS requests and results
HTTP client 0x000000080 http client logs
TLS 0x000000400 TLS logs
TCP 0x000000800 TCP logs
LDS 0x000001000 local domain sockets
WebSocket client 0x000004000 logs outgoing websocket connections
App WebSocket 0x000008000 logs app websocket connections (e.g. from PBX objects to an App Service or from the UI to the App Service)
UDP 0x000200000 UDP logs
DTLS 0x000400000 logs DTLS handshake and messages
Media 0x000800000 logs media events
Media channel 0x001000000 logs RTP/SCTP media connections
ICE 0x002000000 logs ICE messages between peers
TURN 0x004000000 logs TURN messages between peers
AppSharing 0x008000000 logs AppSharing connection
Audio 0x010000000 logs Audio connection and headset events
Video 0x020000000 logs video connection and webcam events
Browser 0x040000000 logs Chromium events
AppProxy 0x080000000 logs requests which are proxied between the local webserver and the remote server
Webserver 0x200000000 enables webserver specific logs

code can be or'ed and used as value for the Log flags field in PBX/Config/myApps/Client Settings.

Windows
On Windows, traces are written to the C:\Users\[UserName]\AppData\Local\innovaphone\myApps directory.
  • myApps-date-time.txt : main log file for the platform services
  • myAppsOutlookSearch-date-time.txt : log file for the Outlook phone book access
  • myAppsHookController-date-time.txt : log file for the hot-key interceptor (see Hot keys)
myApps update traces are written to the %windir%\temp\ directory.
  • myAppsInstall.txt: MSI installation file
  • myAppsUpdateService-date-time.txt: myApps update service traces


Android
traces can be sent by e-mail.
also, an Android device might also be connected to a PC via an USB cable to get the traces. The files can be found in Android/data/com.innovaphone.clientandroid/files
iOS
traces can be sent by e-mail.

Related Articles