Meter an app, bot, or assistant

curl (verify your key first)

curl -sS -X POST https://fxmacrodata.com/partner-meter/v1/audience \
  -H "Authorization: Bearer $FXMD_KEY" \
  -H "Content-Type: application/json" \
  -d '{"surface_id":"Acme Markets iOS","user_ref":"testuser0000000000000000000000000000000000000000000000000000abcd"}'

# {"ok":true,"event_id":"accepted-audience_ping-..."}

Node.js / Express

import { createHmac } from "node:crypto";
import { logger } from "./your-server-logger.js";   // pino, winston, whatever you use

const SURFACE = "Acme Markets iOS";

async function reportAudience(userId) {
  const userRef = createHmac("sha256", process.env.FXMD_METER_SECRET)
    .update(String(userId)).digest("hex");
  try {
    const res = await fetch("https://fxmacrodata.com/partner-meter/v1/audience", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.FXMD_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ surface_id: SURFACE, user_ref: userRef }),
      signal: AbortSignal.timeout(3000),
    });
    if (!res.ok) logger.warn("fxmd meter", res.status, await res.text());
  } catch (err) {
    logger.warn("fxmd meter failed", err.message);    // never rethrow
  }
}

app.get("/api/calendar", async (req, res) => {
  void reportAudience(req.user.id);                   // do not await
  res.json(await calendarCache.get());
});

Next.js route handler

// app/api/calendar/route.ts  -  runs on the server, key stays server-side
import { after } from "next/server";

export async function GET() {
  const session = await auth();
  after(() => reportAudience(session.user.id));   // after the response is sent
  return Response.json(await getCalendar());
}

Python / FastAPI

import hashlib, hmac, os, httpx
from fastapi import BackgroundTasks, Depends

METER_URL = "https://fxmacrodata.com/partner-meter/v1/audience"
SURFACE = "Acme Markets iOS"

def user_ref(user_id: str) -> str:
    return hmac.new(os.environ["FXMD_METER_SECRET"].encode(),
                    str(user_id).encode(), hashlib.sha256).hexdigest()

async def report_audience(user_id: str) -> None:
    try:
        async with httpx.AsyncClient(timeout=3.0) as client:
            await client.post(
                METER_URL,
                headers={"Authorization": f"Bearer {os.environ['FXMD_API_KEY']}"},
                json={"surface_id": SURFACE, "user_ref": user_ref(user_id)},
            )
    except Exception as exc:
        logger.warning("fxmd meter failed: %s", exc)

@app.get("/api/calendar")
async def calendar(tasks: BackgroundTasks, user=Depends(current_user)):
    tasks.add_task(report_audience, user.id)
    return await calendar_cache.get()

Django

# Celery keeps the meter off the request path entirely.
@shared_task(ignore_result=True)
def report_audience(user_id):
    requests.post(
        "https://fxmacrodata.com/partner-meter/v1/audience",
        headers={"Authorization": f"Bearer {settings.FXMD_API_KEY}"},
        json={"surface_id": settings.FXMD_SURFACE, "user_ref": user_ref(user_id)},
        timeout=3,
    )

class CalendarView(APIView):
    def get(self, request):
        report_audience.delay(request.user.pk)
        return Response(calendar_cache.get())

Go

func ReportAudience(ctx context.Context, userID string) {
    body, _ := json.Marshal(map[string]string{
        "surface_id": surface,
        "user_ref":   userRef(userID),
    })
    ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()
    req, _ := http.NewRequestWithContext(ctx, http.MethodPost,
        "https://fxmacrodata.com/partner-meter/v1/audience", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("FXMD_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        log.Printf("fxmd meter: %v", err)
        return
    }
    defer resp.Body.Close()
}

PHP / Laravel

// app/Jobs/ReportAudience.php
public function handle(): void
{
    Http::withToken(config('services.fxmd.key'))
        ->timeout(3)
        ->post('https://fxmacrodata.com/partner-meter/v1/audience', [
            'surface_id' => config('services.fxmd.surface'),
            'user_ref'   => hash_hmac('sha256', $this->userId, config('services.fxmd.secret')),
        ]);
}

// Controller
ReportAudience::dispatch($request->user()->id)->afterResponse();

Ruby on Rails

class ReportAudienceJob < ApplicationJob
  def perform(user_id)
    ref = OpenSSL::HMAC.hexdigest("SHA256", ENV.fetch("FXMD_METER_SECRET"), user_id.to_s)
    Faraday.post("https://fxmacrodata.com/partner-meter/v1/audience") do |req|
      req.headers["Authorization"] = "Bearer #{ENV.fetch('FXMD_API_KEY')}"
      req.headers["Content-Type"] = "application/json"
      req.options.timeout = 3
      req.body = { surface_id: ENV.fetch("FXMD_SURFACE"), user_ref: ref }.to_json
    end
  rescue => e
    Rails.logger.warn("fxmd meter failed: #{e.message}")
  end
end

Java / Spring Boot

@Async
public void reportAudience(String userId) {
    var body = Map.of("surface_id", surface, "user_ref", userRef(userId));
    try {
        restClient.post()
            .uri("https://fxmacrodata.com/partner-meter/v1/audience")
            .header("Authorization", "Bearer " + apiKey)
            .contentType(MediaType.APPLICATION_JSON)
            .body(body)
            .retrieve()
            .toBodilessEntity();
    } catch (RestClientException ex) {
        log.warn("fxmd meter failed: {}", ex.getMessage());
    }
}

ASP.NET Core

public async Task ReportAudienceAsync(string userId, CancellationToken ct)
{
    var payload = new { surface_id = _surface, user_ref = UserRef(userId) };
    var request = new HttpRequestMessage(HttpMethod.Post,
        "https://fxmacrodata.com/partner-meter/v1/audience")
    {
        Content = JsonContent.Create(payload)
    };
    request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", _apiKey);
    try { await _http.SendAsync(request, ct); }
    catch (Exception ex) { _logger.LogWarning(ex, "fxmd meter failed"); }
}

Firebase Cloud Functions

exports.calendar = functions
  .runWith({ secrets: ["FXMD_API_KEY", "FXMD_METER_SECRET"] })
  .https.onCall(async (data, context) => {
    if (!context.auth) throw new functions.https.HttpsError("unauthenticated", "sign in");
    await reportAudience(context.auth.uid);      // uid is already stable and internal
    return calendarCache.get();
  });

Supabase edge function

Deno.serve(async (req) => {
  const { data: { user } } = await supabase.auth.getUser(req.headers.get("Authorization"));
  const key = new TextEncoder().encode(Deno.env.get("FXMD_METER_SECRET"));
  const mac = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" },
                                            false, ["sign"]);
  const sig = await crypto.subtle.sign("HMAC", mac, new TextEncoder().encode(user.id));
  const userRef = [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");

  await fetch("https://fxmacrodata.com/partner-meter/v1/audience", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${Deno.env.get("FXMD_API_KEY")}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ surface_id: "Acme Markets iOS", user_ref: userRef }),
  });
  return Response.json(await getCalendar());
});

Cloudflare Worker

export default {
  async fetch(request, env, ctx) {
    const userId = await authenticate(request, env);
    ctx.waitUntil(reportAudience(userId, env));   // runs after the response
    return Response.json(await calendar(env));
  },
};

A Worker is a server, so the key is safe there. A Worker that simply proxies our API to your app is not: that is API mirroring and the licence prohibits it. Cache and reshape, do not relay.

Any scheduler (cron, Cloud Scheduler, Sidekiq, Hangfire)

#!/usr/bin/env bash
# Nightly: report everyone who opened the calendar screen since yesterday.
psql -At -c "select id from users where calendar_seen_at > now() - interval '1 day'" \
| while read -r uid; do
    ref=$(printf '%s' "$uid" | openssl dgst -sha256 -hmac "$FXMD_METER_SECRET" -r | cut -d' ' -f1)
    curl -sS -o /dev/null -X POST https://fxmacrodata.com/partner-meter/v1/audience \
      -H "Authorization: Bearer $FXMD_KEY" -H "Content-Type: application/json" \
      -d "{\"surface_id\":\"Acme Markets iOS\",\"user_ref\":\"$ref\"}"
  done