Laravel Adobe Analytics Laravel Package

Getting Started

• Install the package with Composer, then publish its config:

  composer require vendor/adobe-analytics-laravel
  php artisan vendor:publish --tag="adobe-analytics-config"
  

• Add credentials to .env:

  ADOBE_ANALYTICS_CLIENT_ID=
  ADOBE_ANALYTICS_CLIENT_SECRET=
  ADOBE_ANALYTICS_ORG_ID=
  # Optional for local smoke tests only:
  ADOBE_ANALYTICS_ACCESS_TOKEN=
  

• First verify authentication with the lowest-risk call: list report suites.

  use Vendor\AdobeAnalytics\Facades\AdobeAnalytics;
  
  $suites = AdobeAnalytics::reportSuites()->list();
  

• Then run a small report against a known report suite:

  $report = AdobeAnalytics::reports()->run([
      'rsid' => 'my-report-suite',
      'dimension' => 'variables/page',
      'metrics' => ['metrics/visits'],
      'dateRange' => 'last7Days',
  ]);
  

• Look first at:
  • config/adobe-analytics.php for credentials, cache store, token TTL, HTTP timeout, and static-token override.
  • The package README for exact method names and payload shapes.
  • The client/service classes for report suite, dimension, metric, segment, and report-run methods.
  • The package tests for expected Adobe request payloads and response handling.

Implementation Patterns

• Resolve the client through the container or inject it into your own service class rather than calling the facade everywhere. This keeps report logic testable and lets you swap in a fake client.
• Wrap report execution in your own application service, e.g. AnalyticsReportService, so controllers and jobs do not know Adobe-specific payload details.
• Treat report runs as potentially asynchronous. A common pattern is:
  1. Create the report run.
  2. Poll the run status with backoff.
  3. Fetch and cache the completed report data.
  4. Store normalized results if you need historical dashboards.
• Use queued jobs for anything beyond a smoke test. Adobe report runs can be slow, and queue workers give you retries, timeouts, and backoff without blocking HTTP requests.
• Cache discovery data aggressively:
  • Report suites, dimensions, metrics, and segments change infrequently.
  • Cache them with a long TTL and use a key that includes the Adobe org/client ID.
• Cache report results with a shorter TTL keyed by report suite, dimension, metrics, date range, segment, and filters.
• For dashboards, separate “metadata discovery” from “report data refresh”. Refresh metadata nightly and report data on a schedule appropriate to the dashboard.
• Use Laravel’s HTTP client testing tools if the package exposes its underlying client. Otherwise bind a fake implementation of the package client into the container and assert your application service calls it with the right payload.
• For local development and CI, use the static access token override to avoid real OAuth calls. For production, use the cached client-credentials flow.
• If you support multiple Adobe orgs or business units, avoid relying on a single global config. Build a small factory that creates a client per org with its own credentials and cache namespace.

Gotchas and Tips

• The OAuth token cache is critical. Use a shared cache store such as Redis or the database in multi-server deployments; file cache can cause each server to request its own token.
• Set a token TTL safety buffer, e.g. 60 seconds before actual expiry, to avoid clock skew and in-flight request failures. If the package exposes a TTL config, lower it below the Adobe-issued expiry.
• Include the Adobe org ID and client ID in token cache keys. Otherwise rotating credentials or switching orgs can reuse the wrong token.
• The static access token override bypasses refresh logic. Use it only for local testing, CI, or short-lived debugging. Never commit it, and remember it will expire without automatic renewal.
• Report runs are usually asynchronous. Do not assume run() returns data immediately. Check whether the package polls for you; if not, implement polling with exponential backoff and a hard timeout.
• Adobe Analytics identifiers are not human-readable. Dimensions look like variables/page, metrics look like metrics/visits, and report suites use IDs rather than display names. Build a cached mapping layer from discovery endpoints.
• Missing OAuth scopes or missing Analytics product profile access typically surfaces as 403. After changing Adobe IMS permissions, clear the cached token; otherwise you may keep using a token issued before the permission change.
• Handle 429 responses with Retry-After and jittered backoff. Avoid launching many report runs in parallel; Adobe rate limits can affect all jobs using the same credentials.
• Be explicit about date ranges and timezones. Adobe report suite timezone can differ from your application timezone, and relative ranges like last7Days are evaluated in Adobe’s context.
• List endpoints may paginate. Do not assume the first response contains every report suite, dimension, metric, or segment. Check the package’s pagination support and loop until exhausted.
• After changing .env values, run php artisan config:clear. In production, ensure php artisan config:cache still receives credentials through config files, not direct env() calls outside config.
• For debugging, enable HTTP logging temporarily and inspect Adobe error codes/messages and request IDs. Use the static token to isolate authentication problems from report payload problems.
• Extension points to look for: publishable config, custom cache store, configurable HTTP timeout/retry, custom token provider binding, and replaceable HTTP client for testing.