Browser Content

适用于浏览器扩展的 Content Script。

工作原理

Content Script 运行在网页上下文中，无法直接发起跨域 HTTP 请求到 localhost:5842。因此 Content Script 版本的 SDK 通过 chrome.runtime.sendMessage 将日志发送给 Background Script，由 Background Script 代为转发。

Content Script                    Background Script
──────────────                    ─────────────────
logger.info('clicked')
  │
  └──chrome.runtime.sendMessage──▶  registerContentBridge(logger)
                                      │
                                      └──▶ logger.info('clicked')
                                             └──▶ HTTP → Server

前提条件

Background Script 必须先调用 registerContentBridge(logger) 注册监听器。参见 Browser Background 页面。

导入

import { createLogger } from '@duty/logs-sdk/browser-content';

初始化

const logger = createLogger({
  appId: 'my-extension',
  appName: 'My Browser Extension',
  version: '1.0.0',
  apiKey: 'your-api-key',
});

TIP

虽然 Content Script 不直接发送 HTTP 请求，但 apiKey 仍需传入以保持接口一致。实际的 API Key 校验发生在 Background Script 端。

记录日志

用法与其他入口完全一致：

logger.info('页面加载', { url: location.href });
logger.warn('元素未找到', { selector: '#target' });
logger.error('操作失败', { action: 'click', error: 'element detached' });

健康检查

Content Script 的健康检查通过 chrome.runtime.sendMessage 发送 DUTY_LOG_HEALTH 消息给 Background Script。如果 Background Script 不可用（扩展被禁用等），SDK 会自动切换到 BUFFERING 模式。

完整示例

// content.ts
import { createLogger } from '@duty/logs-sdk/browser-content';

const logger = createLogger({
  appId: 'duty-helper',
  appName: 'Duty Helper Extension',
  version: '1.0.0',
  apiKey: 'your-api-key',
});

// 监听页面事件并记录日志
document.addEventListener('click', (e) => {
  const target = e.target as HTMLElement;
  logger.info('用户点击', {
    tag: target.tagName,
    id: target.id,
    text: target.textContent?.slice(0, 50),
  });
});