@gravity-ai/react

中文文档
1.7.0发布于 2026/11/15MITTypeScriptESM + CJS零依赖近 30 天下载 63.9万

渲染重力AI广告的反应组件

中文使用文档
文档目录15 节
  1. 安装
  2. 快速启动
  3. API 响应形状
  4. 构成部分
  5. <GravityAd />
  6. MCP 连接广告
  7. 服务器交付的放置设计
  8. 数据绘制单位
  9. 风格与 style 财务报告和审定财务报表 slotProps
  10. <GravityLeadFormAd /> (折旧)
  11. <AdText />
  12. 印象跟踪
  13. 钩子
  14. useAdTracking
  15. 许可证

@ gravity-ai/反应

以自动印象和点击跟踪方式渲染重力广告的回放组件.

关于经主机同意的作曲插入,见 即时行动广告。 。 。 .

安装

npm install @gravity-ai/react

对等依赖:反应17+

快速启动

import { GravityAd } from '@gravity-ai/react';

function ChatResponse({ ads }) {
  return ads.map((ad, i) => <GravityAd key={i} ad={ad} />);
}

就是这样。 当响应包含服务器交付时 renderer_spec,组件验证并使得投放设计。 否则,它会回到被捆绑的牌。 它在广告滚动到视图时会自动放出印象像素.

API 响应形状

组件期望重力 API 返回的对象 :

interface AdResponse {
  adText: string;
  title?: string;
  cta?: string;
  brandName?: string;
  url?: string;
  favicon?: string;
  impUrl?: string;    // impression tracking pixel
  clickUrl?: string;  // tracked click-through URL
  renderer_spec?: RendererSpec | string; // optional server-delivered placement design
}

构成部分

<GravityAd />

带有自动印象/点击跟踪功能的全功能化广告渲染器. Bundled变体使用内置样式;服务器交付设计使用经验证的内置声明外加可选语义CSS变量. 不需要CSS-in-JS运行时间.

<GravityAd
  ad={ad}
  // Leave `variant` unset to accept the placement's server-delivered design.
  showLabel={true}
  labelText="Sponsored"
  openInNewTab={true}
  onImpression={() => console.log('seen')}
  onClickTracked={() => console.log('clicked')}
/>

备选案文:

备选案文说明
card默认. 带有边框、阴影和粘贴的垂直卡.
inline侧边栏或工具栏的水平布局 .
minimal没有边框 影子 也没有背景 有主机内容的混合.

通过 variant 刻意地将其中一副被捆绑的相片接上,忽略 renderer_spec。只有在出版商必须拥有本地版式时才使用.

MCP 连接广告

过 onConnect 当您的应用程序有 MCP 客户端时 。 带有效广告的广告 connect 有效载荷(type: 'mcp',一个 https serverUrl页:1 name,可选的 https iconUrl按钮复制到 cta 然后制作一个连接卡片:品牌、标题、身体和一个贴有标签的按钮 cta。该卡没有添加自己的文本.

<GravityAd
  ad={ad}
  onConnect={(request) => connectMcpServer(request.serverUrl, request.name)}
/>

onConnect 接收 { id, serverUrl, name, iconUrl? } 返回时 { status: 'connected' | 'declined' | 'failed' }直接或作为承诺。 它在点击器内同步运行, 所以在任何开始前打开 OAuth 弹出 await。每次连接点击的背景中,跟踪点击点火。 没有网站倒退:当结果是 declined 或者说 failed,或者回调投出,没有打开,卡片保持不变,所以用户可以再次尝试. 当连接等待重用时, 重复点击 。 无 onConnect或带有无效有效载荷,该广告作为普通广告制作。 当广告同时带有可用即时动作和可使用连接时,连接卡只在 onConnect 已经设定.

此组件仅使: 声明 supportsMcpConnect: true 匹配您的广告请求的位置( t)@gravity-ai/ui自我牵引 GravityAd 做这个给你,当 onConnect 已设定).

让SDK运行登录

createMcpConnectHandler 构建一个 onConnect 在浏览器中运行整个MCP授权的处理器,并将连接交给您自己MCP客户端. 它在点击中打开了弹出,发现了服务器的授权服务器(RFC 9728 保护资源元数据,后为 RFC 8414 授权服务器元数据),通过动态客户端注册在下面注册您的应用 clientName,将用户与PKCE(S256)一起送入广告商的同意屏幕 state 第8707号条例 resource,然后将返回的代码交换为符号.

import { GravityAd, createMcpConnectHandler, type McpConnection } from '@gravity-ai/react';

const onConnect = createMcpConnectHandler({
  clientName: 'Acme Chat',
  redirectUri: `${window.location.origin}/mcp/callback`,
  attribution: () => ({ utm_source: 'acme-chat', utm_medium: 'chat' }),
  onConnected: async (connection: McpConnection) => {
    await mcpHub.add({
      name: connection.name,
      url: connection.serverUrl,
      headers: connection.headers,
      oauth: connection.oauth,
    });
  },
});

<GravityAd ad={ad} onConnect={onConnect} />

每个连接在自己的弹出中运行,只接受从弹出回调. 保护资源元数据必须命名 MCP 服务器本身( 来源相同, 服务器路径等于或低于元数据) resource 因此,服务器不能为另一个服务器的资源发布一个符号。 每个请求在15秒后放弃.

结果是 connected 一次 onConnected 决定, declined 当用户关闭弹出(在召回之前的任何时候,也取消仍在运行的请求)或拒绝同意时,以及 failed 否则(无 OAuth 元数据, a) resource 无法匹配服务器、被屏蔽的弹出、被拒绝的注册或令牌交换、a state 不匹配,或 onConnected 抛出。 该连接是:

{
  serverUrl: string;
  name: string;
  headers: { Authorization: 'Bearer …' };
  oauth: { tokenEndpoint: string; clientId: string; refreshToken?: string; expiresAt?: number; resource: string };
}

选项 :

选项目的
clientName你的应用软件的名字,显示在广告商的同意屏幕上.
redirectUri关于您自己来源的页面 completeMcpConnectCallback()。 。 。 .
clientId在广告商注册的客户身份; 跳过动态客户注册 .
attribution返回授权 URL 的跟踪参数。 仅 utm_source, (中文(简体) ), utm_medium, (中文(简体) ), utm_campaign, (中文(简体) ), utm_content, (中文(简体) ), utm_term 财务报告和审定财务报表 grclid ,所以它永远不能覆盖 OAuth 参数.
fetch替换 fetch 用于发现、登记和信使呼叫(见下文CORS).
onConnected接收连接和原始请求.

重定向页面只需调用 completeMcpConnectCallback() 一旦它装入。 它发布代码, state 和在同一源头打开器的任何错误,从地址栏中删除并关闭弹出:

// app/mcp/callback/page.tsx
'use client';
import { useEffect } from 'react';
import { completeMcpConnectCallback } from '@gravity-ai/react';

export default function McpCallback() {
  useEffect(() => { completeMcpConnectCallback(); }, []);
  return <p>Connecting…</p>;
}

在访问符前刷新 oauth.expiresAt 与 refreshMcpConnection,它使用刷新脚本授予并返回更新的连接(当没有刷新符号或服务器拒绝时它拒绝):

import { refreshMcpConnection } from '@gravity-ai/react';

if (connection.oauth.expiresAt && connection.oauth.expiresAt - Date.now() < 60_000) {
  connection = await refreshMcpConnection(connection);
  await mcpHub.update(connection);
}

处理器从不登录携带的符号,代码或URL. 存储 headers 财务报告和审定财务报表 oauth 你存储其他证书的方式.

科斯特语. 浏览器直接调用MCP服务器的元数据,注册端点和符号端点,因此它们必须允许交叉发端请求. 许多人这样做(MCP的参考服务器和Exa的符号端点做),但有些人没有: Exa的注册端点(Ehttps://auth.exa.ai/api/oauth/register)不发送 CORS 头,所以从浏览器中注册失败。 对于此类服务器,通过 a clientId 提前登记或通过 fetch 通过您自己的服务器转发电话:

const relayFetch: typeof fetch = (input, init) =>
  fetch('/api/mcp-oauth-relay', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({
      url: String(input),
      method: init?.method ?? 'GET',
      headers: init?.headers,
      body: init?.body,
    }),
  });

const onConnect = createMcpConnectHandler({ clientName: 'Acme Chat', redirectUri, fetch: relayFetch, onConnected });
const refreshed = await refreshMcpConnection(connection, { fetch: relayFetch });

中继器将请求转发至 url 并返回上游状态, WWW-Authenticate 头和身体。 URL来自广告商的元数据,所以让中继器只接触到公共的https主机,而永远不要转发自己的饼干或证书.

服务器交付的放置设计

重力可以附加一个版本 renderer_spec 对广告回应。 何时 variant 是未设置的, <GravityAd>数字 :

  1. 解析和结构验证光谱.
  2. 确定内容具有约束力(title, (中文(简体) ), adText, (中文(简体) ), cta, (中文(简体) ), brandName, (中文(简体) ), favicon, (中文(简体) ), url) (中文(简体) ).
  3. 应用出版商的语义主题变量.
  4. 通过一个安全的节点白名单( R)box, (中文(简体) ), text, (中文(简体) ), image, (中文(简体) ), link) (中文(简体) ).
  5. 掉回捆绑的地方 card 如果光谱不正确或解析为无内容,则生成器.

标准卡光谱使用一个根链接 url,所以整个可见的广告路线通过 clickUrl它从不筑起锚 光谱必须包括明显的披露,例如: AD, (中文(简体) ), Sponsored, (中文(简体) ), Promoted,或 Paid如果缺少披露,SDK会覆盖其内置的广告徽章.

网络广告请求应当发送 specCapabilities: "web1" (而且不能发送) supportsSpec: false) (中文(简体) ). 现有发送两个字段的集成仍为后相兼容,被作为出版商放置默认的可网络能力处理.

服务器设计采用这些可选主机变量,倒回SDK调色板:

变量目的
--gravity-bg纸牌/背景表面
--gravity-text主要案文
--gravity-text-muted副文本
--gravity-accentCTA/百分数
--gravity-accent-foreground重音文字
--gravity-muted静态表面
--gravity-border边框
--gravity-radius卡片半径

当a --gravity-* 变量缺失,渲染器使用匹配的主机变量(--card, (中文(简体) ), --foreground, (中文(简体) ), --primary等)于其字形倒置前.

数据绘制单位

当广告携带 unit 财务报告和审定财务报表 variant 是未设置的, <GravityAd> 以符合容器活宽度的布局来绘制,而当宽度跨出布局边界时会回流. 单位取出主机页面的光或暗面,文字颜色和字体; 2; --gravity-accent 财务报告和审定财务报表 --gravity-radius 设置按钮颜色和角半径. rich_frame 在框架主机中渲染的单位, a action_card 按钮运行 onPrompt,则a connect_card 按钮运行 onConnect。一个单位类型或版本的 SDK 并不知道绘图是纯文本卡。 印象和点击跟踪工作 相对于其他的广告,和没有 unit 和以前一样.

如果您自己获取广告,请在每次请求的放置中添加一个单元所需的内容 getPlacementContext数字 :

import { getPlacementContext } from '@gravity-ai/react';

const placements = [{
  placement: 'below_response',
  placement_id: 'main',
  ...getPlacementContext(slotRef.current, { promptAction: !!onPrompt, mcpConnect: !!onConnect }),
}];

它返回槽宽度、主机字体和主题以及能力 <GravityAd> 绘图( e)frames 默认为 true匹配 enableFrames) (中文(简体) ). 它从不扔出; 它只在服务器上返回 capabilities。 。 。 .

风格与 style 财务报告和审定财务报表 slotProps

以 style 道具 :

<GravityAd ad={ad} style={{ maxWidth: 400, borderRadius: 16 }} />

以 slotProps数字 :

<GravityAd
  ad={ad}
  slotProps={{
    cta: { style: { background: '#E11D48', borderRadius: 999 } },
    label: { style: { display: 'none' } },
    title: { style: { fontSize: 16 } },
  }}
/>

每个 slotProps dOM 元素的密钥映射 :

密钥元素它控制着什么
container外部 <a>与顶级相同 style 道具
inner包装纸 <div>布局、 补丁、 间隙
header页眉行 <div>法维康+品牌+标签行
favicon法维孔 <img>大小, 边框射线
brand品牌名称 <span>字体, 颜色
label"赞助" <span>药丸型,能见度
body身体包装器 <div>标题+文本布局
title标题 <p>字体, 颜色
text附加文本 <p>字体, 颜色
ctaCTA 按钮 <span>背景、 边线、 垫地

每个槽接受 { style?: CSSProperties; className?: string }。 。 。 .

关于带有DOM结构和通用食谱的完整型式指南,见 击打.md。 。 。 .

<GravityLeadFormAd /> (折旧)

铅表已退役。 服务器不再返回 leadForm 在广告上,和 <GravityLeadFormAd /> 使无所事事。 使用 <GravityAd /> 换句话说.

<AdText />

无法使用的文本只渲染器 。 需要完全控制演示文稿时使用 .

<AdText
  ad={ad}
  className="my-custom-style"
  style={{ fontSize: 14 }}
/>

渲染器 ad.adText 作为链接(如果 clickUrl 或间距。 没有超出内置样式 text-decoration: none; color: inherit。 。 。 .

印象跟踪

两个部件都使用 IntersectionObserver 点出印象像素 只当广告实际可见时 切换到用户(视图端的50%元素)。 这比起上山起火有了显著的改善——出版商不会报告在折叠线下所制作的广告的印象,这是从未见过的.

每条广告的印象就喷出一次 如果广告对象改变( 不同) impUrl),新广告的追踪重回.

比尔林不变:印象像素(impUrl火力和以前一样 像素仍然点出 50% 的广告进入取景口(或者在上架的地方) IntersectionObserver 页:1 另外,SDK将阴影可视性信标发送到同一个 URL ev=measured, (中文(简体) ), sdk 财务报告和审定财务报表 sv 当像素起火时查询参数,以及 ev=viewable 一次至少50%的广告已经查看了1个连续第二个(MRC可观印象). 信标只是测量,绝不影响计费. 投放到50%以下或隐藏标签会重新启动1秒; 没有信标发送到哪里 IntersectionObserver 无法使用.

要禁用自动跟踪 :

<GravityAd ad={ad} disableImpressionTracking />

钩子

useAdTracking

用于构建完整自定义广告组件的低级钩子 :

import { useAdTracking } from '@gravity-ai/react';

function CustomAd({ ad }) {
  const { containerRef, handleClick } = useAdTracking({
    ad,
    onImpression: () => console.log('impression fired'),
    onClickTracked: () => console.log('click tracked'),
  });

  return (
    <a ref={containerRef} href={ad.clickUrl} onClick={handleClick}>
      {ad.adText}
    </a>
  );
}

钩子返回 :

  • containerRef - 附属于基于互通区观察员的印象跟踪 DOM 元素
  • handleClick ——点击点击启动点击跟踪回调
  • impressionFired ——布尔表示印象是否已经发出

许可证

麻省理工学院

版本与发布记录

@gravity-ai/react 共发布 22 个版本,首次发布于 2025/11/27;过去 12 个月发布了 22 个版本。

版本发布日期距今
1.7.0latest2026/11/151 天前
1.6.02026/11/142 天前
1.5.12026/11/142 天前
1.5.02026/11/143 天前
1.4.02026/11/133 天前
1.3.22026/10/081 个月前

关于 @gravity-ai/react 的常见问题

@gravity-ai/react 是什么?

渲染重力AI广告的反应组件

如何安装 @gravity-ai/react?

在项目目录运行 npm install @gravity-ai/react,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=17.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gravity-ai/react 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gravity-ai/react 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@gravity-ai/react 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=18.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gravity-ai/react 可以商用吗?

@gravity-ai/react 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gravity-ai/react 的下载量有多少?

根据 npm 官方下载统计,@gravity-ai/react 在 2026/10/17 – 2026/11/15 这 30 天内被下载 639,083 次,日均约 21,303 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gravity-ai/react 还在维护吗?

最新版本 1.7.0 发布于 2026/11/15(1 天前);至今共发布 22 个版本,其中过去 12 个月发布了 22 个;首次发布于 2025/11/27。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。