Fang mit App Analytics an

Fügen Sie einer bestehenden App in drei Schritten Analysen hinzu: Speichern Sie ein Ereignis, leiten Sie es über Ihr Backend weiter und verifizieren Sie es in Analytics. Eine spezielle Analysebibliothek ist nicht erforderlich.

Voraussetzungen

• Eine App, die in der App Analytics Vorschau registriert ist, mit aktivierter App-Telemetrie.
• Die in den Anforderungen aufgeführten Berechtigungen.

Schritt 1: Zeichnen Sie ein Ereignis auf

Rufen Sie diesen Code aus einem bestehenden Interaktionshandler auf. Dieses Beispiel protokolliert report_exported nach einem erfolgreichen Berichtsexport:

const logRecord = {
  timeUnixNano: (BigInt(Date.now()) * 1000000n).toString(),
  eventName: 'report_exported',
  attributes: [
    { key: 'databricks.app.analytics.schema.version', value: { intValue: '1' } },
    { key: 'databricks.app.analytics.event.id', value: { stringValue: crypto.randomUUID() } },
    { key: 'databricks.app.analytics.event.type', value: { stringValue: 'action' } },
    { key: 'databricks.app.analytics.event.name', value: { stringValue: 'report_exported' } },
  ],
};

const response = await fetch('/_analytics', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(logRecord),
});
if (!response.ok) throw new Error('Analytics export failed.');

/_analyticsist eine Route, die du deiner App hinzufügst, nicht ein integrierter Azure Databricks-Endpunkt. Schritt 2 zeigt die Export-Logik für seinen Backend-Handler.

session_id ist optional. Wenn Sie eine bereitstellen, verwenden Sie die ursprüngliche Analysesitzung wieder, anstatt für jedes Ereignis eine neue Sitzungs-ID zu generieren. Wenn du ein Ereignis erneut versuchst, sende denselben Eintrag erneut, inklusive ID und Zeitstempel.

Informationen zu Seitenaufrufen, Web Vitals und Aktionseigenschaften finden Sie unter Payload-Beispiele.

Schritt 2: Exportiere aus deinem Backend

Füge deinem bestehenden Backend einen Handler POST /_analytics hinzu. Geben Sie den geparsten und validierten Anforderungskörper an die folgende Funktion weiter. Behalten Sie die Route hinter den Zugriffskontrollen Ihrer App und wenden Sie Ihre bestehenden Anfragelimits und Fehlerbehandlungen an. Der Erfolg wird erst im Browser zurückgegeben, wenn die Funktion erfolgreich ist.

Die Funktion umhüllt den Datensatz in eine OpenTelemetrie-Protokollanfrage (OTLP) und sendet sie an den Collector der App:

async function exportAnalyticsRecord(logRecord) {
  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
  if (endpoint !== 'http://localhost:4314') {
    throw new Error('This example requires the TCP OTLP/HTTP receiver at localhost:4314.');
  }

  const response = await fetch(`${endpoint}/v1/logs`, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      resourceLogs: [
        {
          resource: {
            attributes: [{ key: 'service.name', value: { stringValue: process.env.DATABRICKS_APP_NAME } }],
          },
          scopeLogs: [{ logRecords: [logRecord] }],
        },
      ],
    }),
  });
  if (!response.ok) throw new Error('Collector rejected the request.');
  const text = await response.text();
  const result = text ? JSON.parse(text) : {};
  if (Number(result.partialSuccess?.rejectedLogRecords ?? 0) > 0) {
    throw new Error('Collector rejected the event.');
  }
}

Schritt 3: Verifizieren in Analytics

1. Deployen Sie die Änderungen über den bestehenden Deployment-Workflow Ihrer App und lösen Sie dann die instrumentierte Interaktion aus.
2. Auf der App-Detailseite öffnen Sie Analytics und wählen Sie ein SQL-Warehouse aus.
3. Wenn das Onboarding angezeigt wird, wähle Nach Ereignissen suchen und dann Analytics öffnen, wenn Ereignisse eintreffen.
4. Finden Sie report_exported in Top-Aktionen oder Live-Events.

Die Annahme durch den Collector geht der Aufnahme in die Tabelle voraus. Wenn das Ereignis nicht erscheint, aktualisieren Sie Analytics und überprüfen Sie den Zeitbereich. Befolgen Sie alle von der Benutzeroberfläche angezeigten Berechtigungshinweise. Um die zugrunde liegenden Telemetriedaten zu überprüfen, siehe Telemetriedaten überprüfen.

Weitere Ressourcen

• Was ist App Analytics?
• App Analytics Ereignisschema und Abfragen