Ad-click landings and conversions, aggregated

import app from '@adonisjs/core/services/app'
import { SiteClient } from '@fetchski/attract-cms-sdk'

const site = await app.container.make(SiteClient)
const adsMetrics = await site.adsMetrics().getAdsMetrics()

{
  "from": "2026-09-01T00:00:00.000Z",
  "to": "2026-09-22T00:00:00.000Z",
  "groupBy": [
    "day",
    "platform"
  ],
  "landings": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "day": "2026-09-20",
          "platform": "google"
        },
        "landings": 41
      }
    ]
  },
  "conversions": {
    "groupBy": [
      "day",
      "platform"
    ],
    "rows": [
      {
        "key": {
          "currency": "USD",
          "day": "2026-09-20",
          "platform": "google-ads"
        },
        "conversions": 3,
        "retracted": 0,
        "value": 6400,
        "browserSent": 2,
        "serverSent": 3,
        "serverPending": 0,
        "serverFailed": 0,
        "serverSkipped": 0
      }
    ]
  }
}

In your app

import { inject } from '@adonisjs/core'
import { SiteClient } from '@fetchski/attract-cms-sdk'

@inject()
export default class GetAdsMetricsController {
  constructor(protected site: SiteClient) {}

  async handle() {
    return this.site.adsMetrics().getAdsMetrics()
  }
}

import router from '@adonisjs/core/services/router'

const GetAdsMetricsController = () => import('#controllers/get_ads_metrics_controller')

router.get('/ads-metrics', [GetAdsMetricsController])

curl http://localhost:3333/ads-metrics

• landings — page views whose URL carried an ad click ID, from the Request Log (every visitor counts; nothing identifying is used). Empty while the Request Log is switched off. Only day, platform (google, meta, tiktok, other), utmSource, utmCampaign and landingPath apply.
• conversions — conversion events by when they happened. Always also grouped by currency. value sums restated values and leaves out retracted events. Grouped by platform (a destination such as google-ads), each row adds browser and server delivery outcomes — the delivery success rate.

Behavior

• Access: an API key with ads-metrics:read — or its group master ads:all, or admin:all — or a signed-in user holding the analytics:view permission. Anonymous callers get 404.
• Rate limit: the key’s own reads-per-minute limit, set when the key is created (default 600); over it, 429 with Retry-After. The client waits and retries for you; you see RateLimited only if that runs out.
• Retries: a read is safe to repeat: the client retries it on no answer, a 502/503/504 and a 429.
• Timeout: 15 s per attempt by default; raise timeout (milliseconds) in config/attract.ts for longer.

Test it

import { test } from '@japa/runner'
import app from '@adonisjs/core/services/app'
import { fakeAttract } from '@fetchski/attract-cms-adonis/testing'
import GetAdsMetricsController from '#controllers/get_ads_metrics_controller'

test('adsMetrics.getAdsMetrics', async () => {
  const site = fakeAttract()

  const controller = await app.container.make(GetAdsMetricsController)
  await controller.handle()

  site.assertCalled('adsMetrics.getAdsMetrics')
})

node ace test

Related