feat: add channel parameter (#72)

Author: jpoehnelt

src/index.test.ts

@@ -44,6 +44,10 @@ test.each([
     { url: "https://example.com/js" },
     "https://example.com/js?callback=__googleMapsCallback",
   ],
+  [
+    { channel: "foo" },
+    "https://maps.googleapis.com/maps/api/js?callback=__googleMapsCallback&channel=foo",
+  ],
 ])("createUrl is correct", (options: LoaderOptions, expected: string) => {
   const loader = new Loader(options);
   expect(loader.createUrl()).toEqual(expected);

src/index.ts

@@ -41,6 +41,33 @@ export interface LoaderOptions {
    * See https://developers.google.com/maps/documentation/javascript/get-api-key.
    */
   apiKey: string;
+  /**
+   * To track usage across different applications using the same client ID,
+   * you may provide an optional channel parameter with your requests. By
+   * specifying different channel values for different aspects of your
+   * application, you can determine precisely how your application is used.
+   *
+   * For example, your externally-facing website may access the API using a
+   * channel set to customer while your internal marketing department may use
+   * a channel set to mkting. Your reports will break down usage by those
+   * channel values.
+   *
+   * Channel reporting is available for applications using the Maps JavaScript
+   * API, the image APIs or any of the Google Maps Platform web services.
+   *
+   * The channel parameter must use the following format:
+   *
+   * - Must be an ASCII alphanumeric string.
+   * - Period (.), underscore (_) and hyphen (-) characters are allowed.
+   * - The channel parameter is case-insensitive; upper-case, mixed-case, and
+   *   lower-cased channel parameters will be merged into their lower-case
+   *   equivalent. For example, usage on the `CUSTOMER` channel will be combined
+   *   with the usage on the `customer` channel.
+   * - The channel value must be a static value assigned per application
+   *   instance, and must not be generated dynamically. You may not use
+   *   channel values to track individual users, for example.
+   */
+  channel?: string;
   /**
    * In your application you can specify release channels or version numbers:
    *
@@ -68,7 +95,7 @@ export interface LoaderOptions {
    *
    * If you do not explicitly specify a version, you will receive the
    * weekly version by default.
-   */ 
+   */
   version?: string;
   /**
    * The id of the script tag. Before adding a new script, the Loader will check for an existing one.
@@ -180,6 +207,10 @@ export class Loader {
   /**
    * See [[LoaderOptions.id]]
    */
+  channel: string;
+  /**
+   * See [[LoaderOptions.channel]]
+   */
   id: string;
   /**
    * See [[LoaderOptions.libraries]]
@@ -227,6 +258,7 @@ export class Loader {
    */
   constructor({
     apiKey,
+    channel,
     id = "__googleMapsScriptId",
     libraries = [],
     language,
@@ -238,6 +270,7 @@ export class Loader {
   }: LoaderOptions) {
     this.version = version;
     this.apiKey = apiKey;
+    this.channel = channel;
     this.id = id;
     this.libraries = libraries;
     this.language = language;
@@ -260,6 +293,10 @@ export class Loader {
       url += `&key=${this.apiKey}`;
     }
 
+    if (this.channel) {
+      url += `&channel=${this.channel}`;
+    }
+
     if (this.libraries.length > 0) {
       url += `&libraries=${this.libraries.join(",")}`;
     }