API 说明

本文对智能投放客户端接入主要涉及的 API 进行说明。

  • CdpAdvertisementService:mPaaS 中间层的 CdpAdvertisementService 中封装了智能投放组件的接口,通过调用这些接口,可实现智能投放的相关功能。

  • ActionExecutor:本接口实现展位和广告信息的拦截。拦截时,客户端将不展示相应展位以及广告内容;不拦截时,则展示展位以及广告内容。

  • Refresh:全量更新状态。用于在用户更换地区、用户 ID 等场景下重新请求广告。

CdpAdvertisementService

/**
 * Cdp广告服务接口
 *
 */
public abstract class CdpAdvertisementService extends ExternalService {

    /**
     * 初始化所有广告信息
     *
     * @param extInfo  扩展信息
     * @param callBack 回调
     */
    public abstract void initialized(Map<String, String> extInfo, IAdGetSpaceInfoCallBack callBack);

    /**
     * 通过展位 ID 查询展位,异步callback onSuccess(SpaceInfo spaceInfo)返回查询结果。
     * 若无本地缓存,则callback一次RPC查询结果。
     * 若有本地缓存且未到更新时间,则callback一次本地查询结果。
     * 若有本地缓存且已到更新时间,则callback一次本地查询结果,RPC完毕后再callback一次更新的结果。
     * 仅在RPC失败时会callback onFail()接口。
     *
     * @param spaceCode 展位 ID,需要向投放平台申请
     * @param callback  回调接口
     */
    public abstract void getSpaceInfoByCode(String spaceCode, IAdGetSingleSpaceInfoCallBack callback);

    /**
     * 通过展位 ID查询展位,异步callback onSuccess(SpaceInfo spaceInfo)返回查询结果。
     * 若无本地缓存,则callback一次RPC查询结果。
     * 若有本地缓存且未到更新时间,则callback一次本地查询结果。
     * 若有本地缓存且已到更新时间,则callback一次本地查询结果,RPC完毕后再callback一次更新的结果。
     * 仅在RPC失败时会callback onFail()接口。
     *
     * @param spaceCode   展位 ID,需要向投放平台申请
     * @param extInfo     扩展参数
     * @param immediately 只返回 RPC 结果
     * @param callback    回调接口
     */
    public abstract void getSpaceInfoByCode(String spaceCode, Map<String, String> extInfo, boolean immediately, final IAdGetSingleSpaceInfoCallBack callback);

    /**
     * 通过展位 ID list批量查询展位,异步onSuccess(List<SpaceInfo> adSpaceInfo)返回查询结果。
     * 若无本地缓存,则callback一次RPC查询结果。
     * 若有本地缓存且未到更新时间,则callback一次本地查询结果。
     * 若有本地缓存且已到更新时间,则callback一次本地查询结果,RPC完毕后再callback一次更新的结果。
     * 仅在RPC失败时会callback onFail(List<String> adSpaceCodes)接口。
     *
     * @param spaceCodeList 展位 ID list,需要向投放平台申请
     * @param extInfo       扩展参数
     * @param immediately   只返回RPC结果
     * @param callback      回调接口
     */
    public abstract void batchGetSpaceInfoByCode(List<String> spaceCodeList, Map<String, String> extInfo, boolean immediately, final IAdGetSpaceInfoCallBack callback);

    /**
     * H5 接口
     * 查询并展示广告,目前仅供AdH5Plugin调用
     *
     * @param activity   当前页面
     * @param parentView 父控件
     * @param url        地址
     * @param h5Param    参数
     */
    public abstract void checkAndShowAdInH5(final Activity activity, ViewGroup parentView, String url, String h5Param);

    /**
     * 移除指定spaceCode的广告view
     *
     * @param activity  需要移除公告的页面
     * @param spaceCode 广告 ID
     */
    public abstract void removeAdvertisement(Activity activity, String spaceCode);

    /**
     * 获取 action 执行器,没有设置则返回 null
     *
     * @return action 执行器
     */
    public abstract ActionExecutor getActionExecutor();

    /**
     * 设置 action 执行器
     *
     * @param executor action 执行器
     */
    public abstract void setActionExecutor(ActionExecutor executor);


    /**
     * 设置用户 ID
     *
     * @param userId 用户 ID
     */
    public abstract void setUserId(String userId);

    /**
     * 获取用户 ID
     *
     * @return 用户 ID
     */
    public abstract String getUserId();

    /**
     * 获取广告展位的回调类
     */
    public interface IAdGetSpaceInfoCallBack {
        /**
         * 获取展位信息成功
         *
         * @param adSpaceInfo 展位列表
         */
        void onSuccess(List<SpaceInfo> adSpaceInfo);

        /**
         * 获取展位信息失败
         *
         * @param adSpaceCodes 展位请求code列表
         */
        void onFail(List<String> adSpaceCodes);
    }

    /**
     * 获取单个展位的回调类
     */
    public interface IAdGetSingleSpaceInfoCallBack {
        /**
         * 获取展位信息成功
         *
         * @param spaceInfo 展位信息
         */
        void onSuccess(SpaceInfo spaceInfo);

        /**
         * 失败
         */
        void onFail();
    }
}

ActionExecutor

/**
 * Action 处理器
 *
 */
public interface ActionExecutor {

    /**
     * 是否拦截 Action
     * @param spaceInfo 展位信息
     * @param spaceObjectInfo 广告信息
     * @param url action url
     * @return true表示拦截该 action,false 表示不拦截
     */
    boolean interceptAction(final SpaceInfo spaceInfo, final SpaceObjectInfo spaceObjectInfo, final String url);

    /**
     * 执行Action
     *
     * @param spaceInfo 展位信息
     * @param spaceObjectInfo 广告信息
     * @param url action url
     * @return 1表示执行成功,其他值表示异常
     */
    int executeAction(final SpaceInfo spaceInfo, final SpaceObjectInfo spaceObjectInfo, final String url);
}

Refresh

     /**
     *  全量更新状态回调
     *
     */

   public interface IRefreshZoneCallBack{
        /**
         *  开始刷新
         *
         */
        void onStart();

        /**
         * 结束刷新
         */
        void onEnd();
    } 

  /**
     * 当用户更换地区、用户id 等场景下重新请求广告
     * @since  3.0
     * @param callBack
     */
   public abstract void refresh(IRefreshZoneCallBack callBack);
阿里云首页 移动开发平台 mPaaS 相关技术圈