@dpgradio/creative 7.0.5 → 7.1.0

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
@@ -140,6 +152,18 @@ dataLayer.pushVirtualPageView(brand) // brand is not required when the config is
 dataLayer.pushEvent(event, data)
 ```
 
+With Mixpanel
+```js
+import { mixpanel } from '@dpgradio/creative'
+import Mixpanel from 'mixpanel-browser'
+
+mixpanel.initialize(Mixpanel, {
+    mixpanelId: 'MIXPANEL ID',
+})
+
+mixpanel.trackEvent(event, data)
+```
+
 ## API
 
 With an initialized [configuration](#config):
@@ -188,18 +212,103 @@ 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
 
@@ -264,9 +373,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.5",
+  "version": "7.1.0",
   "description": "Support package for standalone Javascript applications",
   "main": "src/index.js",
   "scripts": {

package/src/{privacy → analytics}/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/analytics/mixpanel.js

@@ -0,0 +1,37 @@
+import privacy from '../privacy/privacy.js'
+
+class Mixpanel {
+  constructor() {
+    this.trackingEvents = false
+    this.trackBacklog = []
+    this.mixpanel = null
+  }
+
+  initialize(Mixpanel, { mixpanelId, trackPageview = true }) {
+    this.mixpanel = Mixpanel
+    privacy.push('analytics', () => {
+      this.mixpanel.init(mixpanelId, {
+        track_pageview: trackPageview,
+        persistence: 'localStorage',
+        api_host: 'https://api-eu.mixpanel.com',
+      })
+
+      while (this.trackBacklog.length > 0) {
+        const { eventName, properties } = this.trackBacklog.shift()
+        this.mixpanel.track(eventName, properties)
+      }
+
+      this.trackingEvents = true
+    })
+  }
+
+  pushEvent(eventName, properties) {
+    if (this.trackingEvents) {
+      this.mixpanel.track(eventName, properties)
+    } else {
+      this.trackBacklog.push({ eventName, properties })
+    }
+  }
+}
+
+export default new Mixpanel()

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

@@ -1,8 +1,13 @@
 export { default as hybrid } from './app/hybrid.js'
 
+// Privacy
 export { default as privacy } from './privacy/privacy.js'
-export { default as dataLayer } from './privacy/dataLayer.js'
 
+// Analytics
+export { default as dataLayer } from './analytics/dataLayer.js'
+export { default as mixpanel } from './analytics/mixpanel.js'
+
+// Websocket
 export { default as socket } from './socket/socket.js'
 
 export { default as configuration, config } from './config/config.js'
@@ -11,8 +16,10 @@ export { default as api } from './api/api.js'
 
 export { default as authentication } from './app/authentication.js'
 
+// Utils
 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/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