原生广告

在 React Native 应用中集成 CloudX 原生广告

原生广告在您自己的内容中展示，而不是在固定的横幅广告位中。CloudXNativeAdView 既可以使用内置模板为您渲染广告，也可以将各个素材交给您自行布局。

原生广告需要 CloudX React Native SDK 3.10.1 或更高版本，并同时支持新架构和旧架构。

模板模式

模板模式是默认方式，也是最快的集成路径。挂载组件、选择模板，SDK 即可渲染整个广告。

import React from 'react';
import { View } from 'react-native';
import { CloudXNativeAdView, CloudXNativeTemplate } from 'cloudx-react-native';

const AD_UNIT_ID = 'feed_native';

export function FeedScreen() {
    return (
        <View>
            <CloudXNativeAdView
                adUnitId={AD_UNIT_ID}
                template={CloudXNativeTemplate.MEDIUM}
                placement="home_feed"
                style={{ height: 260 }}
                onAdLoaded={(adInfo) => {
                    console.log('Native loaded from', adInfo.networkName);
                }}
                onAdLoadFailed={(error) => {
                    console.log('Native failed:', error.code, error.message);
                }}
                onAdRevenuePaid={(adInfo) => {
                    console.log('Native revenue:', adInfo.revenue);
                }}
            />
        </View>
    );
}

该视图没有固有尺寸。请在 style 中设置高度，否则其高度将渲染为 0pt。

模板类型

模板	形态
`CloudXNativeTemplate.SMALL`	紧凑单行：图标、标题、广告主、行动号召按钮
`CloudXNativeTemplate.MEDIUM`	默认模板。图标、标题、正文、行动号召按钮
`CloudXNativeTemplate.MEDIA_BANNER`	以素材为主的横向版式
`CloudXNativeTemplate.VERTICAL_MEDIA`	全屏竖版，适用于信息流式的竖屏场景

template 在广告加载时读取。在已挂载的视图上修改该属性，需等到下次加载才会生效。

手动模式

设置 renderMode="manual" 可使用您自己的布局来构建广告。挂载所需的素材组件后，SDK 会填充内容，并为其注册点击与展示跟踪。

import React from 'react';
import { View, StyleSheet } from 'react-native';
import {
    CloudXNativeAdView,
    CloudXTitleView,
    CloudXAdvertiserView,
    CloudXBodyView,
    CloudXCallToActionView,
    CloudXIconView,
    CloudXOptionsView,
    CloudXMediaView,
} from 'cloudx-react-native';

export function CustomNativeAd() {
    return (
        <CloudXNativeAdView
            adUnitId="feed_native"
            renderMode="manual"
            style={styles.card}
            onAdLoaded={(adInfo) => console.log('Loaded', adInfo.nativeAd?.title)}
        >
            <View style={styles.row}>
                <CloudXIconView style={styles.icon} />
                <View style={styles.text}>
                    <CloudXTitleView style={styles.title} />
                    <CloudXAdvertiserView style={styles.advertiser} />
                </View>
                <CloudXOptionsView style={styles.options} />
            </View>

            <CloudXMediaView style={styles.media} />
            <CloudXBodyView style={styles.body} />
            <CloudXCallToActionView style={styles.cta} />
        </CloudXNativeAdView>
    );
}

可用的素材组件：CloudXTitleView、CloudXAdvertiserView、CloudXBodyView、CloudXCallToActionView、CloudXIconView、CloudXOptionsView、CloudXMediaView、CloudXStarRatingView。

只需挂载您的布局实际使用的素材。SDK 会等待您挂载的素材，并忽略其余部分。

视频

原生素材可能包含视频。以下三个属性控制播放行为，并且对两种渲染模式均生效。

<CloudXNativeAdView
    adUnitId="reels_native"
    template={CloudXNativeTemplate.VERTICAL_MEDIA}
    disableVideoFullScreen
    startVideoUnmuted={false}
    hideVideoMediaControls
/>

属性	作用
`disableVideoFullScreen`	阻止素材在点击时展开为全屏
`startVideoUnmuted`	以非静音方式开始播放
`hideVideoMediaControls`	隐藏素材自带的播放控件

回调

回调	触发时机
`onAdLoaded`	广告已就绪。`adInfo.nativeAd` 中包含素材的元数据
`onAdLoadFailed`	未返回广告
`onAdDisplayFailed`	广告已加载但无法展示
`onAdClicked`	用户点击了广告
`onAdRevenuePaid`	已记录并计费一次展示
`onAdExpired`	持有的广告在展示前已过期
`onAdClosed`	用户关闭了广告

重新加载

组件在挂载时加载广告，在卸载时销毁广告，因此大多数集成无需使用 ref。

import { useRef } from 'react';
import { CloudXNativeAdView } from 'cloudx-react-native';
import type { CloudXNativeAdViewHandle } from 'cloudx-react-native';

function FeedAd() {
    const ref = useRef<CloudXNativeAdViewHandle>(null);

    // 重新投放该广告位当前持有的广告。
    const reload = () => ref.current?.loadAd();

    // 丢弃该广告。下一次 loadAd() 将发起新的竞价。
    const discard = () => ref.current?.destroyAd();

    return <CloudXNativeAdView ref={ref} adUnitId="feed_native" />;
}

信息流

每个广告位的并发加载数量有限，且组件不会重试失败的加载。在信息流中，请逐个加载广告位，而不是一次性挂载所有广告位，否则大部分广告位将无法填充。