团队 App 内部分析

Teams app和People & Teams平台软件包的综合分析软件包. 这个 软件包提供类型安全分析事件定义、上下文提供者和测试工具 跟踪用户互动和系统行为.

目录

• 概览
• 建筑
• 添加新事件
• 分析背景
• 测试分析

概览

本软件包执行结构化分析系统,即:

• 类型安全: 所有事件和属性都强烈输入
• 声明: YAML 规格文件中定义的事件
• 等级: 对丰富的元数据支持嵌入分析背景
• 可测试:包括综合测试设施
• 频道专用: 向专栏开火 peopleTeams 分析通道

建筑

analytics.spec.yaml          ← Event definitions (YAML)
        ↓
   Code Generation           ← Generates TypeScript types & hooks
        ↓
Generated Files:
├── analytics.types.ts       ← Type definitions for events
├── create-event-payload.ts  ← Event payload creation logic
└── use-analytics-events.ts  ← React hook for firing events
        ↓
    Consumers		     	 ← Use hook to fire analytics events
        ↓
Analytics Listeners          ← Events sent to 'peopleTeams' channel

添加新事件

1. 定义事件 内 analytics.spec.yaml数字 :

事件定义文件规格

- button clicked (addUserToTeam):
    type: ui
    description: description of when this event fires
    attributes:
      <<: *PackageMetaDataContext
      newAttribute:
        type: string
        description: description of the new attribute

2. 再生类型数字 :

yarn analytics:codegen

3. 使用新事件数字 :

import React from 'react';
import { useAnalyticsEvents } from '@atlaskit/teams-app-internal-analytics';

function TeamMemberButton() {
    const { fireEvent } = useAnalyticsEvents();

    const handleClick = () => {
        fireEvent('ui.button.clicked.addUserToTeam', {
            testAttribute: 'memberInvite',
        });
    };

    return <button onClick={handleClick}>Invite Member</button>;
}

事件命名公约

事件遵循此命名模式 :

• UI 事件数字 : ui.[actionSubject].[action].[actionSubjectId]
• 音轨事件数字 : track.[actionSubject].[action].[actionSubjectId]
• 业务活动数字 : operational.[actionSubject].[action].[actionSubjectId]
• 屏幕事件数字 : screen.[screenName].viewed

分析背景

这个 PeopleTeamsAnalyticsContext 提供自动包含在 所有事件 由儿童部分发射.

嵌入上下文

<PeopleTeamsAnalyticsContext
    data={{
        source: 'teamsApp',
        attributes: { consumer: 'web' },
    }}
>
    <PeopleTeamsAnalyticsContext
        data={{
            source: 'teamsProfilePage',
            attributes: { teamId: 'team-123' },
        }}
    >
        <TeamProfile />
    </PeopleTeamsAnalyticsContext>
</PeopleTeamsAnalyticsContext>

结果事件有效载荷:

{
    "eventType": "ui",
    "actionSubject": "button",
    "action": "clicked",
    "actionSubjectId": "analyticsExample",
    "source": "teamsProfilePage",
    "attributes": {
        "packageName": "@atlassian/team-profile",
        "packageVersion": "X.X.X",
        "consumer": "web",
        "teamId": "team-123",
        "testAttribute": "yourValue",
        "sourceHierarchy": "teamsApp.teamsProfilePage"
    }
}

环境优先

当环境被嵌入时,有一个优先系统来确保正确的元数据被附加到 发送至GASv3的事件. 重复数据按下列顺序解决:

1. 事件数据 (最高优先级)
2. 内在上下文数据
3. 外部环境数据

说明: 背景情况 attributes 只有在事件来自 peopleTeamsCtx 命名空间,例如 TeamsAppAnalyticsContext 从这个包裹。 其他事件有效载荷属性 喜欢 source 将附加到所有事件,而不论上下文名称空间.

测试分析

此套件包括测试帮助您校验分析事件被正确发送到 GASv3 (英语). 这些公用事业使用来自 PeopleTeamsAnalyticsListener,确保 事件有效载荷(包括所有提供的情况)与预期成果相匹配.

基本测试设置

import {
    createMockAnalyticsClient,
    renderWithAnalyticsListener,
} from '@atlaskit/teams-app-internal-analytics/test-utils';

const mockClient = createMockAnalyticsClient();

test('should fire analytics event on button click', async () => {
    const { user, mockClient, expectEventToBeFired } = renderWithAnalyticsListener(
        <PeopleTeamsAnalyticsContext data={{ source: 'teamsApp' }}>
            <ButtonWithAnalytics testId="analytics-button" />
        </PeopleTeamsAnalyticsContext>,
        { mockClient },
    );

    // Trigger the event
    await user.click(screen.getByTestId('analytics-button'));

    // Verify the event was fired correctly
    expectEventToBeFired('ui', {
        actionSubject: 'button',
        action: 'clicked',
        actionSubjectId: 'analyticsExample',
        source: 'teamsApp',
        attributes: expect.objectContaining({
            testAttribute: 'expectedValue',
        }),
    });
});