Table of Contents

Authentication and connecting

TTMSFNCCloudGoogleAnalytics reads reporting data from a Google Analytics account, so every session begins with OAuth 2.0 authentication. You register an OAuth client in the Google Cloud console, hand its client ID and secret to the component, and let it run the consent flow. Once the user has approved access, the component holds an access token (and a refresh token) that authorize every subsequent reporting request. This chapter covers configuring those credentials, persisting the tokens so users sign in only once, and confirming the connection before you query data.

OAuth credentials

Three properties on Authentication drive the OAuth flow:

Property Purpose
Authentication.ClientID The OAuth client ID from the Google Cloud console.
Authentication.Secret The matching client secret.
Authentication.CallBackURL The local redirect URI that receives the authorization code, e.g. http://127.0.0.1:8888. It must match a redirect URI registered for the OAuth client.

ViewID identifies which Analytics reporting view (profile) the requests target. Set it once during setup; every request in Building report requests uses it.

Token reuse across runs

Calling Connect the first time opens the system browser for the consent screen. To avoid repeating that on every launch, persist the tokens: set PersistTokens.Location to plIniFile and PersistTokens.Key to a writable file path, then call LoadTokens before connecting. When valid tokens already exist on disk, Connect reuses them silently; otherwise it falls back to the browser consent flow and stores fresh tokens.

Connecting

Wire OnConnected before calling Connect so you know exactly when the tokens are valid and it is safe to issue a request. Connect is asynchronous — it returns immediately and raises OnConnected once authentication completes.

procedure TForm1.SetupAnalytics;
begin
  FAnalytics := TTMSFNCCloudGoogleAnalytics.Create(Self);

  // OAuth 2.0 client credentials from the Google Cloud console.
  FAnalytics.Authentication.ClientID := '<your-client-id>.apps.googleusercontent.com';
  FAnalytics.Authentication.Secret := '<your-client-secret>';
  FAnalytics.Authentication.CallBackURL := 'http://127.0.0.1:8888';

  // Persist the access and refresh tokens so the user is not asked to sign in every run.
  FAnalytics.PersistTokens.Location := plIniFile;
  FAnalytics.PersistTokens.Key := TTMSFNCUtils.AddBackslash(TTMSFNCUtils.GetDocumentsPath)
    + FAnalytics.ClassName + '.ini';
  FAnalytics.LoadTokens;

  // The reporting view (profile) every request targets.
  FAnalytics.ViewID := '<your-view-id>';

  FAnalytics.OnConnected := AnalyticsConnected;
  // First run opens the browser for consent; later runs reuse the persisted tokens.
  FAnalytics.Connect;
end;

procedure TForm1.AnalyticsConnected(Sender: TObject);
begin
  // Tokens are valid here - it is now safe to build a request and call RetrieveData.
end;

Pitfalls

  • Build the request in OnConnected, not right after Connect. Connect returns before authentication finishes; calling RetrieveData immediately can run before a token exists.
  • The callback URL must match the registered redirect URI exactly, including scheme, host, and port, or the consent flow fails.
  • Keep PersistTokens.Key in a writable, per-user location (the snippet uses the documents folder). A non-writable path silently prevents token reuse, so the consent screen reappears every run.

See also