useAnalyticsApi

Description

Use this hook to load and access the Google Analytics Embed API (gapi).

The hook will run the library loading script from Google, grab the API out from window.gapi (where Google loads it to), and store it as a singleton. It will reference the singleton thereafter, keeping window interaction to a minimum.

State changes that happen outside of React (such as API readiness and authorization) are synchronized across all hooks via a singleton emitter effect. This allows you to use the hook in multiple places while keeping them all in sync.

Usage

import { useAnalyticsApi } from "react-use-analytics-api";

Then in your function component:

const { ready, gapi, authorized, error } = useAnalyticsApi();

When ready is true, the gapi object will be set to the loaded and ready-to-use Google Analytics Embed API. The gapi object will be undefined until it is ready to use.

The authorized property will be true when the user is authorized, false otherwise. If you authorize via the useAuthorize hook, this property will be updated for all useAnalyticsApi hooks. Otherwise, it will be set to the last known value when the hook was instantiated.

If something goes wrong, error will tell you what happened.

Using The API Itself

Changes via the gapi API happen outside of the React ecosystem and often need to occur after rendering is completed. For instance, when rendering a chart via the API, content is injected directly into a DOM element. That DOM element must be fully rendered or else you'll get an error.

Therefore, any time you interact with gapi, it should be treated as a side-effect.

This library also provides helper hooks for the API's built-in components:

• useAuthorize - Authorize the user
• useViewSelector - Render an Analytics ViewSelector
• useDataChart - Render a DataChart
• useData - Query data from the Google Analytics Core Reporting API and get back the results
• useSignOut - Sign the user out

If you need to do anything with the API outside of these operations, be sure to use an effect and do cleanup where appropriate.

Signature

useAnalyticsApi() => { ready: boolean; gapi?: GoogleAnalyticsEmbedAPI; authorized: boolean; error?: Error; }

Arguments

The hook takes no arguments.

Return

The hook returns an object containing:

Example

The following demonstrates loading the Google Analytics Embed API and showing whether the user is authorized.

See the useAuthorize hook example to test logging in and out, and see the useDataChart hook example for a full example of everything this library offers.

import * as React from "react";
import { useAnalyticsApi } from "react-use-analytics-api";

export function UseAnalyticsApiExample() {
  const { ready, gapi, authorized, error } = useAnalyticsApi();
  if (error) {
    console.error(error);
  }
  return (
    <div>
      {!error &&
        (ready && !!gapi ? (
          <>
            <div>✔️ Loaded and ready to use!</div>
            {authorized && <div>☀️ Logged into Google Analytics!</div>}
            {!authorized && <div>🔐 Not logged into Google Analytics</div>}
          </>
        ) : (
          <div>⌛ Loading...</div>
        ))}
      {error && (
        <div>
          <div style={{ fontSize: "120%" }}>❌ Error</div>
          <hr style={{ border: 0, borderTop: "solid 1px rosybrown" }} />
          <p>{error.toString()}</p>
          <p>See the console for more information.</p>
        </div>
      )}
    </div>
  );
}