Update Dec 5, 2016: We will soon be releasing an API to detect the platform info (partially in response to the fact that the _host_info URL paramater, which folks had unofficially relied on, needed to be recently removed for Office Online). We also have a temporary workaround in anticipation of the forthcoming official API. See "In Excel Online, OfficeJS API is not passing the host_Info_ parameter anymore to Excel Add-In" for information on the API and workaround.
I am keeping the old answer below, as it is still relevant for most light-up scenarios. Platform-detection should still be used sparingly, as querying API sets give you more fine-grained control, and ensures that your add-in "lights up" new features when they are added to a particular platform].
It sounds like you're describing a "light-up" scenario. For these sort of use cases, it isn't so much the actual version that you care about (do you really want to keep an internal list of all the minimum versions -- of Excel desktop, and soon Excel Online and iOS, and keep that updated?), but rather, you want to check the capability that something is present. And then offer a differentiated experience depending on whether the capability is there or not.
To that end, I would recommend a brand-new API that we just released alongside these APIs (and that is back-ported to all previous versions -- so as long as you're using the latest Office.js from the CDN, you should be good to go). That API offers you the ability to check, at runtime, whether a particular API set is supported. It looks like:
if (Office.context.requirements.isSetSupported('ExcelApi', 1.1)) {
// Do something that is only available via the new APIs
}
Official documentation for it is forthcoming shortly, and our sample will soon start using it as well. Stay tuned...
The current set of newly-released Excel APIs is all under "ExcelApi" version 1.1. As we add new APIs, we'll add them to a 1.2 set, 1.3 set, and so on (and mark in the documentation and IntelliSense what set version each API is available in). Does that make sense?
For completeness sake, a few other things to note about Office.js versioning:
1) To ensure that you have the latest APIs, bug fixes, etc., you should always use the CDN location, which gets updated in-place as we roll out new features. That location is https://appsforoffice.microsoft.com/lib/1/hosted/office.js. https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js also works, with the "1" version being just an alias to "1.1" at the moment... but long-term, it's probably best to switch over to the "1" URL.
2) Corollary to the above: you should always use the latest CDN location even for older hosts. That way, you both get "light-up" for new features, and bug fixes (including for older host versions). Basically, you can always use the latest CDN, and rely on the dynamic loading of Office.js script to load the actual host-specific files you need.
3) You can use the new isSetSupported API for both the new API sets "ExcelApi" and "WordApi", and for existing sets (e.g., "MatrixBinding").
4) For APIs that are part of the "Office." namespace, you can also use "defensive programming" to do runtime checks for individual functions (e.g., check that Office.context.document.bindings && Office.context.document.bindings.addFromSelectionAsync) are supported. However, you can see that this can get quite verbose, so checking for a set should be much easier. Also, this will NOT work for APIs under the "Excel" or "Word" namespaces, so all the more reason to use the Office.context.requirements.isSetSupported API.
5) Finally: for apps that ONLY make sense to run if a given requirement set is present, you can specify the API set in the app's manifest. That being said, a manifest check is about specifying the absolute minimum essentials, without which the app simply won't run (or even show up as available in the insert dialog). A runtime check, meanwhile, lets you control how you want to react if a particular API is unsupported (offering the option of "lightup" features, or a downgraded experience). So, I would generally recommend using the lowest manifest-requirement that makes sense for your app, and then doing runtime checks to light up for new features.
Hope this helps,
~ Michael Zlatkovsky
Developer on Office Extensibility team, MSFT
