@dpgradio/creative 7.0.4 → 7.0.6

package/README.md

@@ -1,5 +1,17 @@
 # @dpgradio/creative
 
+Table of contents:
+* [Installation](#installation)
+* [CSS: Fonts and Colors](#css-fonts-and-colors)
+* [Config](#config)
+* [Privacy and Tracking](#privacy-and-tracking)
+* [API](#api)
+* [Socket](#socket)
+* [Hybrid](#hybrid)
+* [Authentication](#authentication)
+* [Sharing Generator](#sharing-generator)
+* [Utilities](#utilities)
+
 ## Installation
 
 ```bash
@@ -188,17 +200,122 @@ socket.join({ station: stationId, entity: 'plays', action: 'play', options: { ba
 
 ## Hybrid
 
+The app interaction layer for use in webviews in the app.
+Interacts trough a "JavaScript bridge".
+On iOS it uses [message handlers](https://developer.apple.com/documentation/webkit/wkscriptmessagehandler) and on Android it uses [JavascriptInterface](https://developer.android.com/guide/webapps/webview#BindingJavaScript).
+
 ```js
 import { hyrid } from '@dpgradio/creative'
+```
 
-hybrid.appInfo
-hybrid.isNativeApp()
-hybrid.isVersion({ iOS, Android })
-hybrid.call(method, options)
-hybrid.on(method, callback, once)
-hybrid.one(method, callback)
+### Information
+
+#### `hybrid.appInfo()`
+
+Gives information about the brand, platform, version etc. of the app.
+
+#### `hybrid.isNativeApp()`
+
+Returns `true` if the client is a native app.
+
+#### `hybrid.isVersion({ iOS, Android })`
+
+Returns `true` if the client is a native app and the version is equal to or lower than the given version for the given platform.
+
+### Listen for events
+
+The app will emit events that can be listened to.
+For certain events, such as `appLoad` it is important to start listening as soon as possible.
+Because this is sometimes difficult to do, the `appLoaded` method can be used to wait for the `appLoad` event.
+And if the event has already been emitted before the method is called, it will return immediately.
+
+The following events are available:
+* `appLoad`: The app has loaded. If the user is logged in, it provides their radio token.
+* `authenticated`: The user has authenticated. It provides the user's radio token.
+* `didAppear`: The webview is visible. If the user is logged in, it provides their radio token.  ⚠️ Test when exactly this event is emitted.
+* `didHide`: The webview is hidden. ⚠️ Test when exactly this event is emitted.
+
+#### `hybrid.on(event, callback, once)`
+
+Listen for an event. If `once` is `true`, the callback will only be called once.
+
+#### `hybrid.one(event, callback)`
+
+Listen for an event. The callback will only be called once.
+
+#### `hybrid.appLoaded()`
+
+This method returns a promise that resolves when the `appLoad` event is emitted.
+If the event has already been emitted before the method is called, it will return immediately.
+
+If the user is logged in, the user's radio token is returned.
+
+Example usage:
+```
 const radioToken = await hybrid.appLoaded()
-hybrid.decodeRadioToken(radioToken)
+await api.members.me()
+```
+
+### Actions
+
+To initiate actions on the app side, we provide the methods below.
+
+Under the hood these actions are called using the following method, which can also be used directly in case you need to call an action that is not available as a method:
+
+```
+hybrid.call(method, options)
+```
+
+You may encounter the method `"navigateTo"` in older code.
+This method is now deprecated and replaced by `hybrid.openUrl` and `hybrid.openPermalink`.
+
+#### `hybrid.openUrl(url, { mode })`
+
+Opens an external URL in a mode of choice.
+This is not meant to open URLs on our own domains, e.g. `https://qmusic.be/this-is-a-cool-article`.
+For that, use `hybrid.openPermalink`.
+
+Supported modes:
+* `seque`: Opens the URL in a windows that slides from the right, pushing onto the current page.
+* `overlay`: Opens the URL in a full-screen modal that slides up from the bottom.
+* `in-app-browser`: Opens the URL in an in-app browser with navigation controls. No hybrid functionality supported.
+* `external-browser`: Opens the URL in the default browser. No hybrid functionality supported.
+
+#### `hybrid.openPermalink(permalink)`
+
+Opens a permalink of e.g. an article.
+The article will be shown in a regular `seque` style.
+
+⚠️ As of October 2023, not yet supported by the apps.
+
+#### `hybrid.showAuthentication()`
+
+Shows an authentication dialog.
+
+On Android this is shown regardless of the login status, on iOS it's only shown when the user is not logged in.
+
+#### `hybrid.changeHeight(height, { animated })`
+
+Changes the height of the webview.
+
+## Authentication
+
+```js
+import { authentication } from '@dpgradio/creative'
+
+// Call once, at least before requiring authentication somewhere
+authentication.initialize()
+
+// Main usage: prompts for login if needed and sets the token in the API client
+await authentication.require()
+
+
+// Potentially helpful methods (but not required for typical usage)
+authentication.isLoggedIn()
+authentication.onRadioTokenChange(callback)
+authentication.onLogin(callback)
+authentication.askForLogin() // Does the same as require(), but does not await the result
+authentication.radioToken
 ```
 
 ## Sharing Generator
@@ -244,9 +361,10 @@ This package provides a number of utility functions.
 | Function                                                  | Description                                                                              |
 | --------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | `loadScript(url, { timeout })`                            | Dynammically loads a JS script.                                                          |
-| `openLink(url)`                                           | App-compatible link opener.                                                              |
+| `openExternalUrl(url)`                                    | Opens external URL as separate from the current page as possible on web/app.             |
 | `tap(value, callback)`                                    | Invokes `callback` with the `value` and then returns `value`.                            |
 | `cdnImageUrl(endpoint[, size])`                           | Get a full image URL for an endpoint in a given size (`w480`, `w800`, `w1200`, `w2400`). |
 | `cdnUrl(endpoint)`                                        | Get a full CDN URL for a given endpoint.                                                 |
 | `removePhoneNumberCountryPrefix(phoneNumber, [, prefix])` | Removes a country prefix from a phone number based on the station config `country_code`. |
 | `onLocalStorageChange(key, callback)`                     | Calls `callback` when the value of `key` in `localStorage` changes.                      |
+| `decodeRadioToken(token)`                                 | Decodes a JWT radio token.                                                               |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dpgradio/creative",
-  "version": "7.0.4",
+  "version": "7.0.6",
   "description": "Support package for standalone Javascript applications",
   "main": "src/index.js",
   "scripts": {

package/src/app/authentication.js

@@ -4,6 +4,14 @@ import { onLocalStorageChange } from '../utils/onLocalStorageChange.js'
 
 export const RADIO_TOKEN_LOCAL_STORAGE_KEY = 'radio-auth-token'
 
+const inDevelopment = () => {
+  try {
+    return import.meta.env?.DEV
+  } catch (error) {
+    return false
+  }
+}
+
 class Authentication {
   constructor() {
     this.radioToken = null
@@ -19,7 +27,14 @@ class Authentication {
         this.setToken(radioToken)
       }
     })
-    hybrid.on('authenticated', ({ radioToken }) => this.setToken(radioToken))
+    hybrid.on('authenticated', ({ radioToken }) => {
+      this.setToken(radioToken)
+    })
+    // When a user logs in or out in another view of the app than the one we're currently in,
+    // we need to update the token once the user returns to this view.
+    hybrid.on('didAppear', ({ radioToken }) => {
+      this.setToken(radioToken ?? null)
+    })
     onLocalStorageChange(RADIO_TOKEN_LOCAL_STORAGE_KEY, (token) => this.setToken(token), true)
   }
 
@@ -43,7 +58,7 @@ class Authentication {
   askForLogin() {
     this.markAskingForLogin(true)
 
-    if (import.meta?.env?.DEV) {
+    if (inDevelopment()) {
       this.setToken(prompt('[DEVELOPMENT] Please enter your radio token:'))
     } else if (hybrid.isNativeApp()) {
       hybrid.call('showAuthentication', { tier: 'light' })
@@ -70,7 +85,11 @@ class Authentication {
     return new Promise((resolve, reject) => {
       const onCompletion = () => (this.radioToken ? resolve() : reject('There is no authenticated user.'))
       this.onRadioTokenChange(onCompletion)
-      this.askingForLoginListeners.push(onCompletion)
+      this.askingForLoginListeners.push((askingForLogin) => {
+        if (!askingForLogin) {
+          onCompletion()
+        }
+      })
 
       this.askForLogin()
     })

package/src/app/hybrid.js

@@ -1,14 +1,21 @@
-import jwtDecode from 'jwt-decode'
+import decodeRadioToken from '../utils/decodeRadioToken.js'
 
 // Modern versions of the radio apps set up specific User-Agents:
 // Android User-Agent: Qmusic/7.6.1 (nl.qmusic.app; build:21726; Android 11; Sdk:30; Manufacturer:OnePlus; Model: IN2013) OkHttp/ 4.9.1
 // iOS User-Agent: Joe/265 (be.vmma.joe.app; build:1; iOS 14.8.1) Alamofire/265
-const androidRegexp =
+const ANDROID_APP_REGEX =
   /^(?<brand>.+)\/(?<storeVersion>[0-9.]+) \((?<buildName>.+); build:(?<buildVersion>\d+); (?<platform>Android) (?<osVersion>\d+); Sdk:(?<sdkVersion>\d+); Manufacturer:(?<manufacturer>.+); Model: (?<model>.+)\)/
-const iOSRegexp =
+const IOS_APP_REGEX =
   /^(?<brand>.+)\/(?<buildVersion>[0-9.]+) \((?<buildName>.+); build:(?<internalBuildVersion>\d+); (?<platform>iOS) (?<osVersion>\d+\.\d+\.\d+)\)/
 
 class Hybrid {
+  OPEN_URL_MODES = {
+    SEQUE: 'seque',
+    OVERLAY: 'overlay',
+    IN_APP_BROWSER: 'in-app-browser',
+    EXTERNAL_BROWSER: 'external-browser',
+  }
+
   constructor() {
     // Hook this on window so it can be required in multiple packs
     window._hybridEventSubscriptions = window._hybridEventSubscriptions || {}
@@ -92,8 +99,8 @@ class Hybrid {
   }
 
   detectApp(userAgent) {
-    for (const regexp of [androidRegexp, iOSRegexp]) {
-      const match = userAgent.match(regexp)
+    for (const regex of [ANDROID_APP_REGEX, IOS_APP_REGEX]) {
+      const match = userAgent.match(regex)
       if (match) {
         return match.groups
       }
@@ -101,8 +108,59 @@ class Hybrid {
     return { platform: 'browser' }
   }
 
+  /**
+   * @deprecated Use the {@link decodeRadioToken} helper instead.
+   */
   decodeRadioToken(token) {
-    return jwtDecode(token)
+    return decodeRadioToken(token)
+  }
+
+  /**
+   * Opens an external URL.
+   *
+   * Supported modes:
+   * - `seque`: Opens the URL in a windows that slides from the right, pushing onto the current page.
+   * - `overlay`: Opens the URL in a full-screen modal that slides up from the bottom.
+   * - `in-app-browser`: Opens the URL in an in-app browser with navigation controls. No hybrid functionality supported.
+   * - `external-browser`: Opens the URL in the default browser. No hybrid functionality supported.
+   *
+   * This replaces the `navigateTo` method which is now deprecated.
+   */
+  openUrl(url, { mode = 'overlay' } = {}) {
+    if (!Object.values(this.OPEN_URL_MODES).includes(mode)) {
+      throw new Error(
+        `Invalid openUrl mode: "${mode}", supported modes are "${Object.values(this.OPEN_URL_MODES).join('", "')}".`
+      )
+    }
+
+    this.call('openUrl', { url, mode })
+  }
+
+  /**
+   * Opens a permalink of e.g. an article. The article will be shown in a regular `seque` style.
+   *
+   * As of October 2023, not yet supported by the apps.
+   */
+  openPermalink(permalink) {
+    this.call('openPermalink', { permalink })
+  }
+
+  /**
+   * Shows an authentication dialog.
+   *
+   * On Android this is shown regardless of the login status, on iOS it's only shown when the user is not logged in.
+   */
+  showAuthentication() {
+    this.call('showAuthentication', { tier: 'light' })
+  }
+
+  /**
+   * Changes the height of the webview.
+   *
+   * Animation is only supported on Android.
+   */
+  changeHeight(height, { animated = false } = {}) {
+    this.call('changeHeight', { height, animated })
   }
 }
 

package/src/index.js

@@ -13,6 +13,7 @@ export { default as authentication } from './app/authentication.js'
 
 export { default as loadScript } from './utils/loadScript.js'
 export { default as openLink } from './utils/openLink.js'
+export { default as openExternalUrl } from './utils/openExternalUrl.js'
 export { default as tap } from './utils/tap.js'
 export { cdnImageUrl, cdnUrl } from './utils/cdnUrl.js'
 export { removePhoneNumberCountryPrefix } from './utils/phoneNumber.js'

package/src/privacy/dataLayer.js

@@ -1,5 +1,6 @@
 import hybrid from '../app/hybrid.js'
 import { config } from '../config/config.js'
+import decodeRadioToken from '../utils/decodeRadioToken.js'
 import loadScript from '../utils/loadScript.js'
 
 class DataLayer {
@@ -83,7 +84,7 @@ class DataLayer {
 
   setUserInformation(radioToken) {
     this.userInformation = {
-      account_id: hybrid.decodeRadioToken(radioToken).uid,
+      account_id: decodeRadioToken(radioToken).uid,
       loggedIn: true,
     }
   }

package/src/utils/decodeRadioToken.js

@@ -0,0 +1,5 @@
+import jwtDecode from 'jwt-decode'
+
+export default function decodeRadioToken(token) {
+  return jwtDecode(token)
+}

package/src/utils/openExternalUrl.js

@@ -0,0 +1,20 @@
+import hybrid from '../app/hybrid.js'
+
+/**
+ * Opens an external URL as separate as possible from the current page.
+ *
+ * @param {string} url The absolute URL to open.
+ * @param {object} options Options for opening, includes the app mode see {@link hybrid.OPEN_URL_MODES}.
+ */
+export default function openExternalUrl(url, { appMode = hybrid.OPEN_URL_MODES.IN_APP_BROWSER } = {}) {
+  const chromeAgent = navigator.userAgent.indexOf('Chrome') > -1
+  const safariAgent = chromeAgent ? false : navigator.userAgent.indexOf('Safari') > -1
+
+  if (hybrid.isNativeApp()) {
+    hybrid.openUrl(url, { mode: appMode })
+  } else if (!safariAgent) {
+    window.open(url)
+  } else {
+    window.location = url
+  }
+}

package/src/utils/openLink.js

@@ -1,5 +1,8 @@
 import hybrid from '../app/hybrid.js'
 
+/**
+ * @deprecated Use {@link openExternalUrl} instead.
+ */
 export default function openLink(url) {
   const chromeAgent = navigator.userAgent.indexOf('Chrome') > -1
   const safariAgent = chromeAgent ? false : navigator.userAgent.indexOf('Safari') > -1