> For the complete documentation index, see [llms.txt](https://docs.blueseasx.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blueseasx.com/android/cia-ads.md).

# CIA Ads

CIA (Conversational Intent Ads) is a next-generation ad format introduced by BlueSea for AI chat applications. When requesting an ad, the publisher passes the user's prompt to the BlueSea SDK. Leveraging large language models (LLMs), the SDK analyzes the semantic intent of the user's query and delivers the most relevant advertisement accordingly.

CIA supports multiple creative formats, including images, videos, and HTML creatives, enabling a seamless and engaging user experience while maximizing ad monetization performance.

The diagram below provides an overview of the CIA workflow:

<div align="left"><img src="/files/LPcTKjXuLFSvCkFfaPhX" alt="" height="490" width="703"></div>

1. **Initialize CIA.** When a user enters a chat scenario, the publisher initializes the CIA ad. This step prepares the BlueSea AI model and related services for subsequent ad requests. Initialization is required only once during the application's lifecycle.
2. **Load a CIA Ad.** To request a CIA ad, the publisher passes either the user's latest input or a relevant keyword to the BlueSea SDK through the loadCIA() API.
3. **Semantic Analysis and Ad Matching.** The BlueSea SDK securely encrypts and transmits the request data to BlueSea's proprietary AI platform. On the server side, the AI model analyzes the semantic intent of the user's input and matches it against available advertising inventory to identify the most relevant ad. For privacy protection, user input is used solely for intent analysis and ad matching within BlueSea's AI system and is never shared with advertisers.
4. **Ad Delivery and Rendering.** Once the optimal ad has been selected, the BlueSea AI platform returns the final ad response through the SDK callback. Publishers can then render the ad according to its creative type (Video, Image, or HTML) and integrate it into a native ad experience that aligns with their application's design.

CIA supports Video, Image, and HTML creatives. Based on the returned creative type, publishers can design and render ad placements that best fit their application's native user experience.

The diagram below provides an overview of the supported CIA creative formats and recommended ad presentation styles.

<div align="left"><img src="/files/4jMY869AX0ytkr39e7Tq" alt="" height="490" width="737"></div>

\
After the SDK successfully loads an ad, you can use the getCreativeType(), getAdSize(), and getCreativeSize() methods to obtain the creative type and corresponding size information.

* Video and Image Creatives: Use the getCreativeSize() method to retrieve the creative size. The SDK returns the dimensions (in pixels) of the primary video or image asset, as illustrated in the diagram above.
* HTML Creatives: Use the getAdSize() method to retrieve the ad size. The SDK returns the HTML ad dimensions in density-independent pixels (dp).

Once the creative type and size information have been obtained, you can design the ad layout as follows:

**Video and Image Creatives**

Configure the MediaView size based on the dimensions of the primary creative asset. The SDK automatically scales and renders the video or image within the provided MediaView.

To help publishers create engaging and native ad experiences, the SDK provides the following ad components:

<table data-header-hidden data-search="false"><thead><tr><th width="165.71875"></th><th></th><th></th></tr></thead><tbody><tr><td><strong>Component</strong></td><td><strong>Description</strong></td><td><strong>Requirement</strong></td></tr><tr><td>Context</td><td>Text generated by the SDK to bridge the AI-generated response and the advertisement. Publishers should insert this content into the chat conversation outside of the ad view.</td><td>Recommended</td></tr><tr><td>AdOptionView</td><td>AdChoices icon provided by the SDK.</td><td>Required</td></tr><tr><td>Ad Label</td><td>Advertising disclosure label added by the publisher, such as Sponsored, Promoted, or Ad.</td><td>Required</td></tr><tr><td>Advertiser</td><td>Advertiser name provided by the SDK.</td><td>Required</td></tr><tr><td>Title</td><td>Ad headline provided by the SDK.</td><td>Required</td></tr><tr><td>Description</td><td>Ad description provided by the SDK.</td><td>Required</td></tr><tr><td>MediaView</td><td>Container used to display the video or image creative.</td><td>Required</td></tr><tr><td>Icon</td><td>Advertiser icon provided by the SDK.</td><td>Recommended</td></tr><tr><td>CallToAction</td><td>CTA text provided by the SDK.</td><td>Recommended</td></tr></tbody></table>

**HTML Creatives**

After obtaining the ad size through getAdSize(), simply allocate a view using the returned dimensions and render the HTML ad directly within that container.

The following sections provide detailed instructions for integrating CIA into your application.

### **Step1. Initialize CIA**

Before requesting a CIA ad, you must initialize the CIA placement. During a single application lifecycle, each CIA placement only needs to be initialized once.

Call the `initCIA()` method and provide the CIA Placement ID. The initialization result will be returned through the `OnCIAInitListener` callback.

```
BlueseasxSDK.initCIA("<BlueSea-CIA-pid>", new BlueseasxSDK.OnCIAInitListener() {
   @Override
   public void onInitialized() {
       Log.d(TAG, "cia initialized");
   }

   @Override
   public void onInitFailed(int error, String message) {
       Log.d(TAG, "cia init failed, error=" + error + ", message=" + message);
   }
});
```

`OnCIAInitListener` Callbacks:

* `onInitFailed(int error, String message)`: Invoked when CIA initialization fails. You can use `AdError.getCode()` and `AdError.getMessage()` to retrieve the corresponding error code and error message. For detailed descriptions of each error code, refer to [Test & Error Handling](/android/test-and-error-handling.md)
* `onInitialized()`: Invoked when the CIA placement has been successfully initialized and is ready to serve ads.

### **Step2. Load**

After receiving user input, pass either the user's original query or a keyword generated through your own parsing logic to the BlueSea SDK.

Call the `loadCIA()` method with the CIA Placement ID, along with the context and keyword parameters, to initiate an ad request. Use the `AdLoadCallback<MixAd>` callback to monitor the ad loading result.

```
String context = "I want to buy a new phone, can you give me some advice?";
List<String> keywords = Arrays.asList("phone", "buy", "advice");
BlueseasxSDK.loadCIA("<BluSea-pid>", context, keywords, new AdLoadCallback<MixAd>() {
   @Override
   public void onAdLoadError(@NonNull AdError error) {
       String message = "CIA Load Failed, error code: " + error.getCode() + ", message: " + error.getMessage();
       Log.d(TAG, message);
   }

   @Override
   public void onAdLoaded(@NonNull MixAd ad) {
       Log.d(TAG, "CIA Load Success, ad: " + ad);
   }
});
```

`AdLoadCallback` Callbacks:

* `onAdLoaded(MixAd ad)`: Invoked when a CIA ad is successfully loaded. The returned MixAd object contains all creative assets and metadata required for rendering the ad.
* `onAdFailed(AdError error)`: Invoked when the ad request fails.You can use `AdError.getCode()` and `AdError.getMessage()` to retrieve the corresponding error code and error message. For detailed descriptions of each error code, refer to [Test & Error Handling](/android/test-and-error-handling.md)

> If neither Context nor Keyword is provided in the ad request, the BlueSea SDK will select and serve ads based on available device-level signals and contextual information collected by the SDK.

### **Step3. Show**

CIA supports multiple creative formats, allowing publishers to deliver ad experiences that best match their application's design and user experience requirements.

The following creative types are currently supported:

* Image
* Video
* HTML

When an ad is successfully loaded (`onAdLoaded(MixAd ad)`), you can use the following APIs to determine the creative type and retrieve the corresponding size information:

```
switch (mixAd.getCreativeType()) {
   case DISPLAY:
       //Html
       AdSize htmlSize = mixAd.getAdSize(); // dp unit, 320*90
       break;
   case IMAGE:
	 //Image
	 Size imageSize = mixAd.getCreativeSize(); // px unit, 1080*960
       break;
   case VIDEO:
       //Video
       Size videoSize = mixAd.getCreativeSize(); // px unit, 1080*960
       break;
   default:
       break;
}
```

**For Image and Video creatives,** integrate CIA ads using the same approach as standard native ad implementations. Create and provide a native ad layout XML file that defines the ad presentation. The SDK will populate the corresponding ad assets into the specified UI components.

Refer to the sample layout file below:cia\_ad\_layout.xml

```
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
   android:id="@+id/cia_ad_view"
   android:layout_width="match_parent"
   android:layout_height="wrap_content"
   android:orientation="vertical">
   
   <LinearLayout
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:layout_gravity="center_vertical"
       android:layout_marginBottom="4dp"
       android:gravity="center_vertical"
       android:orientation="horizontal">
       
       <TextView
           android:id="@+id/cia_ad_advertiser"
           android:layout_width="wrap_content"
           android:layout_height="wrap_content"
           android:layout_marginRight="3dp"
           android:textSize="10sp" />
           
       <com.blueseasx.sdk.AdOptionsView
           android:id="@+id/cia_ad_options"
           android:layout_width="13dp"
           android:layout_height="13dp" />
   </LinearLayout>
   <LinearLayout
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:orientation="vertical">

       <TextView
           android:id="@+id/cia_ad_title"
           android:layout_width="wrap_content"
           android:layout_height="wrap_content"
           android:textSize="14sp"
           android:textStyle="bold" />

       <TextView
           android:id="@+id/cia_ad_description"
           android:layout_width="wrap_content"
           android:layout_height="wrap_content"
           android:textSize="12sp" />

       <View
           android:layout_width="match_parent"
           android:layout_height="4dp" />

       <com.blueseasx.sdk.MediaView
           android:id="@+id/cia_ad_media"
           android:layout_width="match_parent"
           android:layout_height="wrap_content" />

       <LinearLayout
           android:layout_width="match_parent"
           android:layout_height="50dp"
           android:layout_marginTop="4dp">

           <ImageView
               android:id="@+id/cia_ad_icon"
               android:layout_width="50dp"
               android:layout_height="50dp"
               android:layout_marginRight="4dp" />

           <Button
               android:id="@+id/cia_ad_cta"
               android:layout_width="0dp"
               android:layout_height="50dp"
               android:layout_weight="1"
               android:background="#80009DFF" />
       </LinearLayout>
   </LinearLayout>
</LinearLayout>
```

```
private void showImageOrVideoCIAAd(FrameLayout adContainer, MixAd mixAd) {
   LayoutInflater.from(adContainer.getContext()).inflate(R.layout.cia_ad_layout, adContainer, true);
   LinearLayout nativeAdView = adContainer.findViewById(R.id.cia_ad_view);
   TextView advertiserView = nativeAdView.findViewById(R.id.cia_ad_advertiser);
   AdOptionsView optionsView = nativeAdView.findViewById(R.id.cia_ad_options);
   TextView adTitleView = nativeAdView.findViewById(R.id.cia_ad_title);
   TextView adDescriptionView = nativeAdView.findViewById(R.id.cia_ad_description);
   MediaView mediaView = nativeAdView.findViewById(R.id.cia_ad_media);
   ImageView adIconView = nativeAdView.findViewById(R.id.cia_ad_icon);
   Button ctaButton = nativeAdView.findViewById(R.id.cia_ad_cta);
   List<View> clickableViews = new ArrayList<>();
   nativeAdView.setVisibility(View.VISIBLE);
   nativeAdView.setTag(AdTag.AD_CONTAINER);
   advertiserView.setText(mixAd.getAdvertiser());
   optionsView.setTag(AdTag.AD_OPTIONS);
   adTitleView.setText(mixAd.getTitle());
   adTitleView.setTag(AdTag.AD_TITLE);
   clickableViews.add(adTitleView);
   adDescriptionView.setText(mixAd.getDescription());
   adDescriptionView.setTag(AdTag.AD_DESCRIPTION);
   clickableViews.add(adDescriptionView);
   ViewTreeObserver observer = mediaView.getViewTreeObserver();
   if (observer != null && observer.isAlive()) {
       observer.addOnGlobalLayoutListener(new ViewTreeObserver.OnGlobalLayoutListener() {
           @Override
           public void onGlobalLayout() {
               ViewTreeObserver observer = mediaView.getViewTreeObserver();
               if (observer != null && observer.isAlive()) {
                   observer.removeOnGlobalLayoutListener(this);
               }
               float aspectRatio = mixAd.getMediaContentAspectRatio();
               int width = mediaView.getMeasuredWidth();
               int height = (int) (width / aspectRatio);
               mediaView.setLayoutParams(new LinearLayout.LayoutParams(width, height));
           }
       });
   }
   adIconView.setTag(AdTag.AD_ICON);
   if (mixAd.hasIcon()) {
       adIconView.setVisibility(View.VISIBLE);
   } else {
       adIconView.setVisibility(View.GONE);
   }
   clickableViews.add(adIconView);
   ctaButton.setText(mixAd.getCallToAction());
   ctaButton.setTag(AdTag.AD_CALL_TO_ACTION);
   clickableViews.add(ctaButton);
   mixAd.registerViewForInteraction(nativeAdView, mediaView, adIconView, optionsView, clickableViews);
}
```

**Rendering API Reference**

```
MixAd.registerViewForInteraction(ViewGroup adView, MediaView mediaView, ImageView adIconView, AdOptionsView adOptionsView, List<View> clickableViews);
```

* **adView**：The root view of the ad layout. This parameter must not be null.
* **mediaView**：The view used to display the primary creative asset (Image or Video)
* **adIconView**：The view used to display the advertiser's icon.
* **adOptionsView**：The view used to display the AdChoices icon provided by the SDK.
* **clickableViews**：A list of views that should be registered as clickable. Currently, only CTA, Title, and Description views are supported. Each view must be assigned the appropriate tag before registration.
* **titile**: set  `AdTag.AD_TITLE`
* **description**: set `AdTag.AD_DESCRIPTION`
* **cta**: set  `AdTag.AD_CALL_TO_ACTION`

**CIA Layout Adaptation APIs**

<table data-header-hidden data-search="false"><thead><tr><th width="196.35546875"></th><th></th></tr></thead><tbody><tr><td><strong>CIA API</strong></td><td><strong>Description</strong></td></tr><tr><td>getTitle()</td><td>ad title</td></tr><tr><td>getDescription()</td><td>ad description</td></tr><tr><td>getCallToAction()</td><td>ad call to action</td></tr><tr><td>getAdvertiser()</td><td>advertiser</td></tr><tr><td>hasIcon()</td><td>whether an icon is provided</td></tr><tr><td>getVideoController()</td><td>video controller, only available after registerViewForInteraction</td></tr><tr><td>getMediaContentAspectRatio()</td><td>ad creative size ratio （w/h）</td></tr></tbody></table>

**For video creatives, you can use the following methods:**

<table data-header-hidden data-search="false"><thead><tr><th width="248.28515625"></th><th></th></tr></thead><tbody><tr><td><strong>VideoController</strong></td><td><strong>Description</strong></td></tr><tr><td>play()</td><td>play the video</td></tr><tr><td>pause()</td><td>pause the video</td></tr><tr><td>mute(boolean mute)</td><td>mute and unmute</td></tr><tr><td>isMuted</td><td>check audio status</td></tr><tr><td>isPlaying</td><td>check video playing status</td></tr><tr><td>isPaused</td><td>check whether the video is paused</td></tr></tbody></table>

To minimize disruption to the user experience during ad display, CIA provides a contextual bridging mechanism that connects AI-generated responses with ad content in a more natural way.

```
String context = MixAd.getConext();
```

CIA Sample：

<div align="left"><img src="/files/NqJxSKbMr025MSjNeC1e" alt="" height="491" width="421"></div>

**For HTML creative types**, once an ad is successfully loaded, you can directly render the ad inside the ad container using the

```
private void showBannerAd(MixAd mixAd) {
   AdSize adSize = mixAd.getAdSize();
   View adView = mixAd.adView();
   if (adView != null) {
       LinearLayout.LayoutParams layoutParams = new LinearLayout.LayoutParams(
               AdSize.dp2px(mAdContainer.getContext(), adSize.getWidth()),
               AdSize.dp2px(mAdContainer.getContext(), adSize.getHeight())
       );
       mAdContainer.addView(adView, layoutParams);
   }
}
```

For all CIA creative types (Image, Video, and HTML), you can register ad event listeners to monitor ad lifecycle events and user interactions.

```
mixAd.setAdListener(new MixAdListener() {
   @Override
   public void onAdDisplayFailed(@NonNull AdError error) {
      //ad show failed
   }
   @Override
   public void onAdDisplayed() {
      //ad show succeeded
   }
   @Override
   public void onAdClicked() {
	//ad has been clicked
   }
});
```

### **Step4. Destroy**

If you no longer need the ad, you can destroy it using the following method:

```
private void destroyAd() {
   if (mixAd != null) {
       mixAd.destroy();
       mixAd = null;
   }
}
```