I have a question regarding what the responsibility is of a 3rd party app implementing the TPSDK for Catalyst is when it comes to refreshing a user's Trimble login? Reading through the documentation I am a little unclear about how often I need to call the "com.trimble.tmm.LOGIN" intent and when, if ever, I need to call the "com.trimble.tmm.RefreshUserToken" intent.
For example, I know that in order to use the TPSDK I need to call the Login intent which will return the user's Trimble ID from TMM which I can then use to instantiate a driver manager object, load drivers, etc. I also know that if the user logs out of their account in TMM or switches users then there will be issues when trying to use the TPSDK and our application will detect this and prompt the user to launch TMM to get the updated Trimble ID or log back into TMM. My main question is there a time in between these two instances when our app should be launching TMM to refresh the user's login? For example, if a user has launched TMM and we have pulled in the Trimble ID and then the user uses our app for several weeks is there a certain time when out application should launch the Login intent again just to keep things refreshed? Also, what is the role of the "RefreshUserToken" intent? I have read through the docs for the TPSDK and it's a bit unclear to me why and when this intent should be used.
Last note, I know the documentation for the TPSDK mentions that there's no harm in launching the Login intent as often as possible but I have found that even when the user is already logged into TMM and the Login intent is launched there is some screen flickering in the UI that I would definitely prefer to avoid. That's my main reason for trying to pin down how I can minimize the amount of times I launch the login intent while also making sure that my application is doing it's job to keep everything refreshed and up to date.
So the easy part of these questions are on timing. The TMM or TID login is basically an OpenID based login - therefore we have two kind of token:
Access token --> lifespan of 14hRefresh token --> lifespan is long (30 days).
So the access token is used for e.g. geoid download and all other web service interactions that happen in the background. It goes stale after 14h but can be refreshed with a refresh token - which typically has a much longer life span (30 days in our case).
The license file itself has also a lifespan of 30 days - so the license must get refreshed within 30 days.
When you login via the corresponding intent TMM will download 'your' license (so the license file is specific per app per user) and TMM will also refresh all licenses it knows about if TMM is running (and not killed). So TMM tries to keep things up to date as well.
If TMM is not running you can use the
intent to update tokens; if you take a look at the facade sample you'll see that we run this in a Timer thread parallel to the facade main model.
So a really granular model would check when a specific user downloaded his license - and then call the RefreshUserToken say after 20 days (if online etc). This means that if the device is online within the 10 days time window the user will not see a TMM login screen - the refresh will happen in the background and there is no UX break.
Alternatively the refreshToken intent can also be called in the beginning - when the license file was loaded from disk and the device is online (so I'm assuming the TID of the user got stored somewhere).
The Login intent works in a similar way - but it might be that the UI flickers slightly. I actually can't remember but thats something we can double check here as well - and see if that flickering is really 'required'.
Hope this helps - I think the important numbers are 14h and more important 30days.
Awesome! So I can use the Login intent at the start to get the user's Trimble ID and download the per-app/per-user license file to the device and then from then on making sure that I call the RefreshUserToken intent at least every 30 days will keep the license and user's login up to date for my app?
Thanks as always Nico for your quick responses and detailed answers, this forum is really an awesome resource for developers using the TPSDK!
and yes. So the important bit from the login is the TID GUID or user GUID (however you want to call it).
With this you can always load the license file from disk which works for 30 days.
Calling RefreshUserToken will get you a new access token which then refreshes the license as well. This has the benefit that the user does not see the login screen as often.
I'll try to get an example in the documentation. My first draft was more confusing (even for myself) then helpful - so I guess its better to think about this a little. But I'll add it to the docu.