# Card Ad

## Add Files for Card Ad Integration

Add `CECardAD.h and CECardAD.m` to your app's build target.

## Request Card Ad Instantly

With `loadAdInstant`, our synchronous method, You will get the result of loading ad directly.

* Import `CECardAD.h`

```objectivec
// MyViewController.m

#import "CECardAD.h"

@interface MyViewController()
```

* Create a CECardAD instance and keep its reference. Load ad with your CECardAD instance.

```objectivec
@interface MyViewController() <CECardADDelegate>
@property (nonatomic, strong) CECardAD *cardAd;
@end

- (void) viewDidLoad()
{
    CERequestInfo *info = [CERequestInfo new];
    info.placement = @"PUT_YOUR_PLACEMENT_STRING_HERE·";
    self.cardAd = [[CECardAD alloc] initWithVideoViewProfile: CEVideoViewProfileCardDefaultProfile];
    NSError *error;
    if ([self.ceCardAD loadAdInstantWithInfo:info error:&error]) {
        // TODO: The logic of render ad.
        [self appendLog:@"Get instant ad succefully"];

    } else {
        if (error) {
            // TODO: The logic of load ad fail.
            NSString * log = [NSString stringWithFormat:@"didFailWithError : %@", error.debugDescription];
            [self appendLog:log];
        }
    }
}
```

## Request Card Ad Asynchronously

loadAdAsyncWithInfo is an asynchronous method, you can set timeout via [CERequestInfo](https://intowow.gitbook.io/crystalexpress-documentation-v3-x/ios-sdk/api-reference/cerequestinfo), and get the result of ad request by CECardADRequestDelegate.

* Import `CECardAD.h` and adopt `CECardADRequestDelegate` protocol in view controller's extension.

```objectivec
// MyViewController.m

#import "CECardAD.h"

@interface MyViewController() <CECardADRequestDelegate>
```

* Create a CECardAD instance and keep its reference. Load ad with your CECardAD instance.

```objectivec
@interface MyViewController() <CECardADRequestDelegate>
@property (nonatomic, strong) CECardAD *cardAd;
@end

- (void) viewDidLoad()
{
    CERequestInfo *info = [CERequestInfo new];
    info.placement = @"PUT_YOUR_PLACEMENT_STRING_HERE·";
    info.timeout = 5;
    self.cardAd = [[CECardAD alloc] initWithVideoViewProfile: CEVideoViewProfileCardDefaultProfile];
    [self.cardAd loadAdAsyncWithInfo:info reqDelegate:self];
}
```

* Implement `CECardADRequestDelegate` to handle ad loaded event.

```objectivec
#pragma mark - CECardADRequestDelegate
- (void)cardADDidLoaded:(CECardAD*)cardAD
{
    //  Called when ad is ready.
    UIView *view = cardAD.adUIView; //  Add this to view hierarchy.
}

- (void)cardADDidFail:(CECardAD *)cardAD withError:(NSError *)error {
    NSLog(@"Failed to load cardAD:%@", error);
}
```

## Add `CECardADEventDelegate` to get the ad event callback.

If you want to trace the click, impression, progress event, please implement CECardADEventDelegate to handle it.

```objectivec
/*!
 *  @brief protocol CECardADEventDelegate that can receive AD events
 */
@protocol CECardADEventDelegate <NSObject>
@optional
/*!
 *  @brief callback while this card ad is clicked by user
 *
 *  @param cardAD CECardAD instance that own this card ad component
 */
- (void) cardADDidClick:(nonnull CECardAD *)cardAD;

/*!
 *  @brief callback while card ad is about to log impression
 *
 *  @param cardAD CECardAD instance that own this card ad component
 */
- (void) cardADWillTrackImpression:(nonnull CECardAD *)cardAD;

/*!
 *  @brief callback while this card ad is video format and muted.
 *
 *  @param cardAD CECardAD instance that own this card ad component
 */
- (void) cardADDidMute:(nonnull CECardAD *)cardAD;

/*!
 *  @brief callback while this card ad is video format and unmuted.
 *
 *  @param cardAD CECardAD instance that own this card ad component
 */
- (void) cardADDidUnmute:(nonnull CECardAD *)cardAD;

/*!
 *  @brief callback while this card ad is video format and start playback.
 *
 *  @param cardAD CECardAD instance that own this card ad component
 */
- (void) cardADDidVideoStart:(nonnull CECardAD *)cardAD;

/*!
 *  @brief callback while this card ad is video format and playback to end.
 *
 *  @param cardAD CECardAD instance that own this card ad component
 */
- (void) cardADDidVideoEnd:(nonnull CECardAD *)cardAD;

/*!
 *  @brief callback while this card ad is video format and progress state.
 *
 *  @param cardAD CECardAD instance that own this card ad component
 *  @param totalDuration this video total duration time (ms)
 *  @param currentPosition this video current play back position time (ms)
 */
- (void) cardADDidVideoProgress:(nonnull CECardAD *)cardAD
                       duration:(int)totalDuration
                       position:(int)currentPosition;

/*!
 *  @brief callback while this card ad ad view ready to do animation
 *
 *  @param cardAD CECardAD instance that own this card ad component
 *  @param adView current display ad view
 */
- (void) cardADOnPullDownAnimation:(nonnull CECardAD *)cardAD withAdView:(nullable UIView *)adView;

/**
 *  @brief callback while this card ad is failed to render
 *
 *  @param cardAD CECardAD instance that own this card ad component
 *  @param error Error for rendering
 */
- (void) cardADOnFailedToRender:(nonnull CECardAD *)cardAD error:(nonnull NSError *)error;
@end
```

### Please refer to [CECardAd](https://intowow.gitbook.io/crystalexpress-documentation-v3-x/ios-sdk/api-reference/cecardad) for more information in detail.