Skip to content

feat: add getInstanceUrl() to plugins SDK to expose Staffbase frontend domain #299

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
maximizeIT merged 2 commits into from
Apr 8, 2026
Merged

feat: add getInstanceUrl() to plugins SDK to expose Staffbase frontend domain #299

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a147b63
feat: add getinstanceurl to client sdk
maximizeIT Apr 7, 2026
4f5a5aa
Update commands.js
maximizeIT Apr 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 54 additions & 25 deletions docs/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,137 +53,166 @@ should be used.</p>
<dt><a href="#getUserContentLocale">getUserContentLocale()</a> ⇒ <code>Promise.&lt;any&gt;</code></dt>
<dd><p>Get the current user&#39;s content locale, fallback to branch default locale</p>
</dd>
<dt><a href="#getInstanceUrl">getInstanceUrl()</a> ⇒ <code>Promise.&lt;string&gt;</code></dt>
<dd><p>Get the Staffbase instance URL / frontend domain.</p>
</dd>
</dl>

<a name="openNativeShareDialog"></a>

## openNativeShareDialog ⇒ <code>Promise.&lt;string&gt;</code>

Open a share dialog on native devices

**Kind**: global constant
**Kind**: global constant

| Param | Type | Description |
| --- | --- | --- |
| Param | Type | Description |
| ------- | ------------------- | -------------------- |
| content | <code>object</code> | 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'
});
```

<a name="deviceCanDownload"></a>

## deviceCanDownload() ⇒ <code>Promise.&lt;boolean&gt;</code>

Check if device is able to perform a download.

**Kind**: global function
<a name="isIosDevice"></a>

## isIosDevice() ⇒ <code>Promise.&lt;boolean&gt;</code>

Check if device is using ios.

**Kind**: global function
<a name="isAndroidDevice"></a>

## isAndroidDevice() ⇒ <code>Promise.&lt;boolean&gt;</code>

Check if device is using android.

**Kind**: global function
<a name="getAppVersion"></a>

## getAppVersion() ⇒ <code>Promise.&lt;string&gt;</code>

Get the version of the Staffbase App.

**Kind**: global function
<a name="isNativeApp"></a>

## isNativeApp() ⇒ <code>Promise.&lt;boolean&gt;</code>

Check if app is native.

**Kind**: global function
<a name="isMobileApp"></a>

## isMobileApp() ⇒ <code>Promise.&lt;boolean&gt;</code>

Check if app is mobile.

**Kind**: global function
<a name="openLink"></a>

## openLink(url) ⇒ <code>Promise.&lt;any&gt;</code>

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 | <code>string</code> | the url to open in the browser |
| Param | Type | Description |
| ----- | ------------------- | ------------------------------ |
| url | <code>string</code> | the url to open in the browser |

<a name="openLinkExternal"></a>

## openLinkExternal(url) ⇒ <code>Promise.&lt;any&gt;</code>

Open a link explicitly in the external browser.

**Kind**: global function
**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| url | <code>string</code> | the url to open in the browser |
| Param | Type | Description |
| ----- | ------------------- | ------------------------------ |
| url | <code>string</code> | the url to open in the browser |

<a name="openLinkInternal"></a>

## openLinkInternal(url) ⇒ <code>Promise.&lt;any&gt;</code>

Open a link explicitly in the internal browser.

**Kind**: global function
**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| url | <code>string</code> | the url to open in the browser |
| Param | Type | Description |
| ----- | ------------------- | ------------------------------ |
| url | <code>string</code> | the url to open in the browser |

<a name="getBranchLanguages"></a>

## getBranchLanguages() ⇒ <code>Promise.&lt;any&gt;</code>

Get all enabled content languages configured in the app.

**Kind**: global function
<a name="getBranchDefaultLanguage"></a>

## getBranchDefaultLanguage() ⇒ <code>Promise.&lt;any&gt;</code>

Get the default content language configured in the app.

**Kind**: global function
<a name="getContentLanguages"></a>

## getContentLanguages() ⇒ <code>Promise.&lt;any&gt;</code>

Get all content languages supported by the app.

**Kind**: global function
<a name="getPreferredContentLocale"></a>

## getPreferredContentLocale(content) ⇒ <code>Promise.&lt;string&gt;</code>

Gets the chosen language from a given content object

**Kind**: global function
**Kind**: global function

| Param | Type | Description |
| --- | --- | --- |
| Param | Type | Description |
| ------- | ----------------------------------------- | ------------------------------------- |
| content | <code>object</code> \| <code>array</code> | 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'
```

<a name="getUserContentLocale"></a>

## getUserContentLocale() ⇒ <code>Promise.&lt;any&gt;</code>

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

**Kind**: global function
<a name="getInstanceUrl"></a>

## getInstanceUrl() ⇒ <code>Promise.&lt;string&gt;</code>

Get the Staffbase instance URL / frontend domain.

**Kind**: global function
118 changes: 66 additions & 52 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -202,56 +214,58 @@ 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

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

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

- **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**

Expand All @@ -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
});
```
Loading
Loading