diff --git a/docs/api.md b/docs/api.md index 198d6fb..b827821 100644 --- a/docs/api.md +++ b/docs/api.md @@ -53,137 +53,166 @@ should be used.

getUserContentLocale()Promise.<any>

Get the current user's content locale, fallback to branch default locale

+
getInstanceUrl()Promise.<string>
+

Get the Staffbase instance URL / frontend domain.

+
## openNativeShareDialog ⇒ Promise.<string> + Open a share dialog on native devices -**Kind**: global constant +**Kind**: global constant -| Param | Type | Description | -| --- | --- | --- | +| Param | Type | Description | +| ------- | ------------------- | -------------------- | | content | object | the content to share | -**Example** +**Example** + ```js openNativeShareDialog({ - image: "https://example.com/test.png", - subject: "The string you would like to use as a subject for the share", - text: "This text is shared", - url: "https://example.com" - }) + image: 'https://example.com/test.png', + subject: 'The string you would like to use as a subject for the share', + text: 'This text is shared', + url: 'https://example.com' +}); ``` + ## deviceCanDownload() ⇒ Promise.<boolean> + Check if device is able to perform a download. **Kind**: global function ## isIosDevice() ⇒ Promise.<boolean> + Check if device is using ios. **Kind**: global function ## isAndroidDevice() ⇒ Promise.<boolean> + Check if device is using android. **Kind**: global function ## getAppVersion() ⇒ Promise.<string> + Get the version of the Staffbase App. **Kind**: global function ## isNativeApp() ⇒ Promise.<boolean> + Check if app is native. **Kind**: global function ## isMobileApp() ⇒ Promise.<boolean> + Check if app is mobile. **Kind**: global function ## openLink(url) ⇒ Promise.<any> + Open a link through the app. Where Staffbase decides which browser (External/Internal) should be used. -**Kind**: global function +**Kind**: global function -| Param | Type | Description | -| --- | --- | --- | -| url | string | the url to open in the browser | +| Param | Type | Description | +| ----- | ------------------- | ------------------------------ | +| url | string | the url to open in the browser | ## openLinkExternal(url) ⇒ Promise.<any> + Open a link explicitly in the external browser. -**Kind**: global function +**Kind**: global function -| Param | Type | Description | -| --- | --- | --- | -| url | string | the url to open in the browser | +| Param | Type | Description | +| ----- | ------------------- | ------------------------------ | +| url | string | the url to open in the browser | ## openLinkInternal(url) ⇒ Promise.<any> + Open a link explicitly in the internal browser. -**Kind**: global function +**Kind**: global function -| Param | Type | Description | -| --- | --- | --- | -| url | string | the url to open in the browser | +| Param | Type | Description | +| ----- | ------------------- | ------------------------------ | +| url | string | the url to open in the browser | ## getBranchLanguages() ⇒ Promise.<any> + Get all enabled content languages configured in the app. **Kind**: global function ## getBranchDefaultLanguage() ⇒ Promise.<any> + Get the default content language configured in the app. **Kind**: global function ## getContentLanguages() ⇒ Promise.<any> + Get all content languages supported by the app. **Kind**: global function ## getPreferredContentLocale(content) ⇒ Promise.<string> + Gets the chosen language from a given content object -**Kind**: global function +**Kind**: global function -| Param | Type | Description | -| --- | --- | --- | +| Param | Type | Description | +| ------- | ----------------------------------------- | ------------------------------------- | | content | object \| array | the content to choose the locale from | -**Example** +**Example** + ```js getPreferredContentLocale(['de_DE', 'en_EN']) // => 'de_DE' getPreferredContentLocale({'de_DE': {1,'eins'}, 'en_EN': {1: 'one'}}) // => 'de_DE' ``` + ## getUserContentLocale() ⇒ Promise.<any> + Get the current user's content locale, fallback to branch default locale **Kind**: global function + + +## getInstanceUrl() ⇒ Promise.<string> + +Get the Staffbase instance URL / frontend domain. + +**Kind**: global function diff --git a/docs/usage.md b/docs/usage.md index 7a9cbc5..272b515 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -59,24 +59,26 @@ So the whole interface is asynchronous as well. Every SDK method returns a promise, which resolves with the requested information or throws an error if something has gone wrong. ```js -PluginSDK.isIosDevice().then(function(isIOS) { +PluginSDK.isIosDevice() + .then(function (isIOS) { console.log('IOS Device: ', isIOS); -}).catch(function(error) { - console.warn('Something went wrong: ', error) -}) + }) + .catch(function (error) { + console.warn('Something went wrong: ', error); + }); ``` To get multiple informations at once, you can use `Promise.all`. ```js Promise.all([PluginSDK.isIosDevice(), PluginSDK.isNativeApp()]) - .then(function(isIOS, isNative) { - console.log('IOS Device: ', isIOS); - console.log('Native App: ', isNative); - }) - .catch(function(error) { - console.warn('Something went wrong: ', error) - }) + .then(function (isIOS, isNative) { + console.log('IOS Device: ', isIOS); + console.log('Native App: ', isNative); + }) + .catch(function (error) { + console.warn('Something went wrong: ', error); + }); ``` ### Getting infos from the Staffbase app @@ -171,8 +173,18 @@ As a developer you can request various informations from the Staffbase app. ```js // example for user with german content locale in an english app getUserContentLocale().then(function (locale) { - console.log(locale); // 'de_DE' - }) + console.log(locale); // 'de_DE' + }); + ``` + +1. `getInstanceUrl` -> string + + the URL of the Staffbase instance (frontend domain) the plugin is embedded in + + ```js + getInstanceUrl().then(function (url) { + console.log(url); // 'https://customer.staffbase.com' + }); ``` ### Invoking native methods @@ -184,16 +196,16 @@ With the SDK you can invoke methods, which are in the scope of the native app. checks a given list of locale tags, or an object with locale tags as keys and returns the matching locale tag as string. ```js - const localesArray = ['de_DE', 'en_US']; - const localesObject = { 'de_DE': {}, 'en_US':{} }; + const localesArray = ['de_DE', 'en_US']; + const localesObject = { de_DE: {}, en_US: {} }; - getPreferredContentLocale(localesArray).then(function (locale) { - console.log(locale); // 'en_US' - }) + getPreferredContentLocale(localesArray).then(function (locale) { + console.log(locale); // 'en_US' + }); - getPreferredContentLocale(localesObject).then(function (locale) { - console.log(locale); // 'en_US' - }) + getPreferredContentLocale(localesObject).then(function (locale) { + console.log(locale); // 'en_US' + }); ``` 2. `openLink` {url: string} -> boolean @@ -202,15 +214,15 @@ With the SDK you can invoke methods, which are in the scope of the native app. which indicates if the link has been opened. This can be used to call the method in a click event ```js - // internal link - openLink('/settings/password').then(function (opened) { - console.log(opened); // true - }) - - // external link - openLink('https://staffbase.com').then(function (opened) { - console.log(opened); // true - }) + // internal link + openLink('/settings/password').then(function (opened) { + console.log(opened); // true + }); + + // external link + openLink('https://staffbase.com').then(function (opened) { + console.log(opened); // true + }); ``` 3. `openLinkExternal` {url: string} -> boolean @@ -218,10 +230,10 @@ With the SDK you can invoke methods, which are in the scope of the native app. open a link in the device browser. Returns a boolean which indicates if the link has been opened. This can be used to call the method in a click event ```js - // external link - openLinkExternal('https://staffbase.com').then(function (opened) { - console.log(opened); // true - }) + // external link + openLinkExternal('https://staffbase.com').then(function (opened) { + console.log(opened); // true + }); ``` 4. `openLinkInternal` {url: string} -> boolean @@ -229,10 +241,10 @@ With the SDK you can invoke methods, which are in the scope of the native app. open a link in the app browser. Returns a boolean which indicates if the link has been opened. This can be used to call the method in a click event ```js - // external link - openLinkInternal('https://staffbase.com').then(function (opened) { - console.log(opened); // true - }) + // external link + openLinkInternal('https://staffbase.com').then(function (opened) { + console.log(opened); // true + }); ``` 5. `openNativeShareDialog` {content: object} -> string @@ -240,18 +252,20 @@ With the SDK you can invoke methods, which are in the scope of the native app. - **native only** - **version > 4.0.0** - open the native share view to share an object consisting of an image link, subject, text or url. - - ```js - const contentObject = {image: "https://example.com/test.png", - subject: "The string you would like to use as a subject for the share", - text: "This text is shared", - url: "https://example.com"}; + open the native share view to share an object consisting of an image link, subject, text or url. - openNativeShareDialog(contentObject).then(function (opened) { - console.log(opened); // true - }) - ``` + ```js + const contentObject = { + image: 'https://example.com/test.png', + subject: 'The string you would like to use as a subject for the share', + text: 'This text is shared', + url: 'https://example.com' + }; + + openNativeShareDialog(contentObject).then(function (opened) { + console.log(opened); // true + }); + ``` 6. `openNativeFileDialog` -> Blob **!experimental** @@ -263,7 +277,7 @@ With the SDK you can invoke methods, which are in the scope of the native app. > Attention! This function is still in development and will have a changed behavior in the future! ```js - openNativeFileDialog().then(function (res) { - console.log('Fileurl: ' + URL.createObjectURL(res)); // blob:d3958f5c-0777-0845-9dcf-2cb28783acaf - }) + openNativeFileDialog().then(function (res) { + console.log('Fileurl: ' + URL.createObjectURL(res)); // blob:d3958f5c-0777-0845-9dcf-2cb28783acaf + }); ``` diff --git a/resources/index.html b/resources/index.html index 3598d4c..5ac191b 100644 --- a/resources/index.html +++ b/resources/index.html @@ -618,6 +618,11 @@
>

                 
+ getInstanceUrl() - Instance URL: +

+                
getContentLanguages() - Content Languages:

                 
@@ -817,6 +822,19 @@
Native Share Dialog
error ); }); + PluginSDK.getInstanceUrl() + .then(function (instanceUrl) { + console.log("Instance URL: ", instanceUrl); + document.getElementById( + "isInstanceUrl" + ).textContent = JSON.stringify(instanceUrl, undefined, 2); + }) + .catch(function (error) { + console.warn( + "Something went wrong with getInstanceUrl(): ", + error + ); + }); PluginSDK.getContentLanguages() .then(function (isContentLangs) { console.log("Content Languages: ", isContentLangs); diff --git a/src/lib/app.js b/src/lib/app.js index ce7155f..8fdb5d5 100644 --- a/src/lib/app.js +++ b/src/lib/app.js @@ -158,3 +158,13 @@ export const getUserContentLocale = async () => { log.debug('app/getUserContentLocale'); return sendMessage(cmd.langInfos).then((res) => res.userContentLocale); }; + +/** + * Get the Staffbase instance URL / frontend domain. + * + * @return {Promise} + */ +export const getInstanceUrl = async () => { + log.debug('app/getInstanceUrl'); + return sendMessage(cmd.instanceUrl); +}; diff --git a/src/lib/connection/commands.js b/src/lib/connection/commands.js index f8c25ea..01680d7 100644 --- a/src/lib/connection/commands.js +++ b/src/lib/connection/commands.js @@ -17,6 +17,7 @@ export const commands = { version: 'app-version', mobile: 'app-mobile', native: 'app-native', + instanceUrl: 'instance-url', openLink: 'openExternalLink', nativeUpload: 'nativeFileUpload', nativeShare: 'nativeShareDialog', diff --git a/src/lib/connection/connector/fallback-handlers.js b/src/lib/connection/connector/fallback-handlers.js index 5fb1b1b..9505d5a 100644 --- a/src/lib/connection/connector/fallback-handlers.js +++ b/src/lib/connection/connector/fallback-handlers.js @@ -175,3 +175,20 @@ export const getUserContentLocale = () => { return locale; }; + +/** + * Get the Staffbase instance URL / frontend domain. + * + * Uses ancestorOrigins when available (chrome/safari in iframe), + * falls back to document.referrer or empty string. + * + * @return {String} the instance URL + */ +export const getInstanceUrl = () => { + log.debug('fallback/getInstanceUrl'); + return ( + (window.location.ancestorOrigins && window.location.ancestorOrigins[0]) || + document.referrer || + '' + ); +}; diff --git a/src/lib/connection/connector/fallback.js b/src/lib/connection/connector/fallback.js index c55d087..99b3f13 100644 --- a/src/lib/connection/connector/fallback.js +++ b/src/lib/connection/connector/fallback.js @@ -70,6 +70,8 @@ export const sendMessage = async (cmd, ...payload) => { return fallbacks.getPreferredContentLocale.apply(null, payload); case action.userContentLocale: return fallbacks.getUserContentLocale(); + case action.instanceUrl: + return fallbacks.getInstanceUrl(); case action.nativeUpload: case action.nativeShare: return fallbacks.unSupported(cmd); diff --git a/src/lib/connection/connector/postmessage.js b/src/lib/connection/connector/postmessage.js index 3bb3ac3..780c50c 100644 --- a/src/lib/connection/connector/postmessage.js +++ b/src/lib/connection/connector/postmessage.js @@ -27,14 +27,15 @@ import log from 'loglevel'; * @static * @return {StaticValueStore} */ -const dataStore = ({ platform, language }) => ({ +const dataStore = ({ platform, language, instance }) => ({ mobile: platform.mobile, version: platform.version, native: !!platform.native, ios: platform.native === 'ios', android: platform.native === 'android', langInfos: language, - branchDefaultLanguage: language.branchDefaultLanguage + branchDefaultLanguage: language.branchDefaultLanguage, + instanceUrl: (instance && instance.url) || '' }); let connection = null; @@ -166,6 +167,7 @@ const sendMessage = case actions.ios: case actions.android: case actions.branchDefaultLang: + case actions.instanceUrl: return store[reversedActions[cmd]]; case actions.langInfos: case actions.openLink: diff --git a/src/main.js b/src/main.js index f62c536..bf0bc6f 100644 --- a/src/main.js +++ b/src/main.js @@ -124,6 +124,13 @@ export const getPreferredContentLocale = async (content) => app.getPreferredCont */ export const getUserContentLocale = async () => app.getUserContentLocale(); +/** + * Get the Staffbase instance URL / frontend domain. + * @function + * @return {Promise} + */ +export const getInstanceUrl = async () => app.getInstanceUrl(); + /** * Open a share dialog on native devices * diff --git a/test/lib/app.test.js b/test/lib/app.test.js index 54d26f7..bd2e7bc 100644 --- a/test/lib/app.test.js +++ b/test/lib/app.test.js @@ -33,7 +33,8 @@ const standardMsg = [ 'abc2', { platform: { native: 'ios', mobile: true, version: mockVersion }, - language: langInfos + language: langInfos, + instance: { url: 'https://example.staffbase.com' } } ]; @@ -86,6 +87,10 @@ describe('app', () => { expect(await App.getUserContentLocale()).toEqual(langInfos.userContentLocale); }); + it('should return the instance url', async () => { + expect(await App.getInstanceUrl()).toEqual('https://example.staffbase.com'); + }); + it('should open links', async () => { messageStub.changeMsg(['SUCCESS', 0, true]); expect(await App.openLink('https://test.de')).toEqual(true); diff --git a/test/lib/connection/connection.test.js b/test/lib/connection/connection.test.js index 8c924d7..de2c9f8 100644 --- a/test/lib/connection/connection.test.js +++ b/test/lib/connection/connection.test.js @@ -25,7 +25,8 @@ const standardMsg36 = [ localizedName: 'Englisch' } } - } + }, + instance: { url: 'https://example.staffbase.com' } } ]; diff --git a/test/lib/connection/connector/__snapshots__/fallback.test.js.snap b/test/lib/connection/connector/__snapshots__/fallback.test.js.snap index b4ba15d..705609e 100644 --- a/test/lib/connection/connector/__snapshots__/fallback.test.js.snap +++ b/test/lib/connection/connector/__snapshots__/fallback.test.js.snap @@ -11,6 +11,8 @@ exports[`connector/fallback connect send function accepts all comands command.br } `; +exports[`connector/fallback connect send function accepts all comands command.instanceUrl 1`] = `""`; + exports[`connector/fallback connect send function accepts all comands command.ios 1`] = `false`; exports[`connector/fallback connect send function accepts all comands command.langInfos 1`] = `