@ 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>数字 :
- 解析和结构验证光谱.
- 确定内容具有约束力(
title, (中文(简体) ),adText, (中文(简体) ),cta, (中文(简体) ),brandName, (中文(简体) ),favicon, (中文(简体) ),url) (中文(简体) ). - 应用出版商的语义主题变量.
- 通过一个安全的节点白名单( R)
box, (中文(简体) ),text, (中文(简体) ),image, (中文(简体) ),link) (中文(简体) ). - 掉回捆绑的地方
card如果光谱不正确或解析为无内容,则生成器.
标准卡光谱使用一个根链接 url,所以整个可见的广告路线通过 clickUrl它从不筑起锚 光谱必须包括明显的披露,例如: AD, (中文(简体) ), Sponsored, (中文(简体) ), Promoted,或 Paid如果缺少披露,SDK会覆盖其内置的广告徽章.
网络广告请求应当发送 specCapabilities: "web1" (而且不能发送) supportsSpec: false) (中文(简体) ). 现有发送两个字段的集成仍为后相兼容,被作为出版商放置默认的可网络能力处理.
服务器设计采用这些可选主机变量,倒回SDK调色板:
| 变量 | 目的 |
|---|---|
--gravity-bg | 纸牌/背景表面 |
--gravity-text | 主要案文 |
--gravity-text-muted | 副文本 |
--gravity-accent | CTA/百分数 |
--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> | 字体, 颜色 |
cta | CTA 按钮 <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——布尔表示印象是否已经发出
许可证
麻省理工学院