# Basic Integration

Native ads are presented to the user via native iOS UI components. This enables you to layout ad assets to match the look and feel of your app. When a placement loads a native ad, you can retrieve the native ad assets wrapped in an instance of type [AATNativeAdData](https://ios-sdk.aatkit.com/references/documentation/aatkit/aatnativeaddata).

### Create Placement

To create an instance of [AATNativeAdPlacement](https://ios-sdk.aatkit.com/references/documentation/aatkit/aatnativeadplacement), use the following API:

{% tabs %}
{% tab title="Swift" %}

```swift
var placement = AATSDK.createNativeAdPlacement(name: "<PLACEMENT_NAME>", supportsMainImage: true)
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
id<AATNativeAdPlacement> placement = [AATSDK createNativeAdPlacementWithName:@"<PLACEMENT_NAME>" supportsMainImage:YES];
```

{% endtab %}
{% endtabs %}

The argument `supportsMainImage` determines if the placement will use the main image asset. Remember that if the main image is used, it must be displayed.

### Listen to Callbacks

Through the use of [AATNativePlacementDelegate](https://ios-sdk.aatkit.com/references/documentation/aatkit/aatnativeplacementdelegate), you can listen to the different placement callbacks.

{% tabs %}
{% tab title="Swift" %}

```swift
placement.delegate = self
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
self.placement.delegate = self;
```

{% endtab %}
{% endtabs %}

### Request Ad

To request a native ad, use the following API:

{% tabs %}
{% tab title="Swift" %}

```swift
placement.reload()
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
[self.nativeAdPlacement reload];
```

{% endtab %}
{% endtabs %}

### Retrieve the Native Ad

After receiving a native ad through the `aatHaveAd(:)` callback, you can retrieve the native ad data of type [AATNativeAdData](https://ios-sdk.aatkit.com/references/documentation/aatkit/aatnativeaddata) using the following API:

{% tabs %}
{% tab title="Swift" %}

```swift
let nativeAd = placement.getNativeAd()
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
id<AATNativeAdData> nativeAd = [self.placement getNativeAd];
```

{% endtab %}
{% endtabs %}

### Report adspace

For native placements, it is necessary to report ad spaces manually. Every time you want to display an native ad, call:

{% tabs %}
{% tab title="Swift" %}

```swift
placement.reportAdSpace()
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
[self.placement reportAdSpace];
```

{% endtab %}
{% endtabs %}

### Ad Info

After loading a native ad, you can access the loaded ad information by accessing the `adInfo` property of the loaded `nativeAd`:

{% tabs %}
{% tab title="Swift" %}

```swift
func aatHaveAd(placement: AATPlacement) {
    // The placement has loaded a new ad
    guard let nativeAd = placement?.getNativeAd() else {
        return
    }
    let adInfo = nativeAd.adInfo
    ...
}
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
- (void)aatHaveAdWithPlacement:(id<AATPlacement>)placement {
    // The placement has loaded a new ad
    id<AATNativeAdData> nativeAd = [self.nativeAdPlacement getNativeAd];
    if (nativeAd) {
        AATAdInfo *adInfo = self.nativeAd.adInfo;
        ...
    }
}
```

{% endtab %}
{% endtabs %}

### Retrieve the Native Assets

These so-called native assets can assemble your native ad, according to your app's look and feel. The following image shows an example native ad and the corresponding AATKit methods for retrieving each asset.

<figure><img src="https://3006681101-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC07HayBzqyav5R2yFhOr%2Fuploads%2F7XgmHbNTn4Ju1Az1P10Z%2FNativeAdAssets.png?alt=media&#x26;token=1af68c13-6cd9-4555-9430-ba51d198162b" alt=""><figcaption><p>Native Ad Assets</p></figcaption></figure>

<figure><img src="https://3006681101-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FC07HayBzqyav5R2yFhOr%2Fuploads%2FmS4t7D62tjUNWN7Q1QI6%2FNative%20Ad%20XIB%20%20Assets.png?alt=media&#x26;token=1b6b02e8-dbcf-4cec-9f10-0755d924c3e2" alt=""><figcaption><p>Native Ad XIB Assets</p></figcaption></figure>

{% tabs %}
{% tab title="Swift" %}

```swift
// Ad Title
titleLabel.text = nativeAd.title
// Ad Icon
let iconImageURL = nativeAd.iconUrl // You should download the icon image using this URL
// Ad Main Image
let mainImageURL = nativeAd.imageUrl // You should download the main image using this URL
// Ad Body
descriptionLabel.text = nativeAd.adDescription ?? "DEFAULT_VALUE"
// Ad Identifier
advertiserLabel.text = nativeAd.advertiser ?? "DEFAULT_VALUE"
// Ad CTA Title
adCTALabel.text = nativeAd.callToAction ?? "DEFAULT_VALUE"
// Ad Rating
if let rating = nativeAd.rating {
    self.ratingLabel.text = "\(rating.value)/\(rating.scale)"
}
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
self.titleLabel.text = self.nativeAd.title;
NSString *iconImageURL = self.nativeAd.iconUrl; // You should download the icon image using this URL
NSString *mainImageURL = self.nativeAd.imageUrl; // You should download the main image using this URL
self.descriptionLabel.text = self.nativeAd.adDescription;
self.advertiserLabel.text = self.nativeAd.advertiser;
self.ctaLabel.text = self.nativeAd.callToAction;
// Rating
if (self.nativeAd.rating != nil) {
    self.ratingLabel.text = [NSString stringWithFormat:@"%d/%d", self.nativeAd.rating.value, self.nativeAd.rating.value];
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
If the ad network provides a rating for the retrieved native ad, [AATNativeAdData](https://ios-sdk.aatkit.com/references/documentation/aatkit/aatnativeaddata) will provide it as an [AATNativeAdRating](https://ios-sdk.aatkit.com/references/documentation/aatkit/aatnativeadrating) instance.
{% endhint %}

### Track Native Ad

A tracking view is a UIView instance that is used by the ad network to track impressions and clicks. This means the instance is checked on runtime whether it's visible on the screen and an impression is counted accordingly. A click is also registered on the instance provided but doesn't have to be a UIButton (subclass of UIView) in order for the click to be registered. It's up to you to decide whether the tracking is big (the whole UIView) or small (a small button). Keep in mind that the ad networks track impressions based on a few conditions being met. A tracking view has to be visible for at least a few seconds on the screen (usually 1-2 seconds), plus a more significant portion of the UIView instance has to be visible (usually \~50% of the view has to be visible). Tracking an impression and registering clicks is thus completely dependent on a tracking view being assigned to the native ad that has been provided by the AATKit.

To set the tracking view, use the `AATNativeAd` method:&#x20;

```swift
func attachToView(_ view: UIView, mainImageView: UIView?, iconView: UIView?, ctaView: UIView?)
```

* `view`: The view that will be used to track impressions and clicks.
* `mainImageView`: The main image asset view.
* `iconView`: The icon asset view.
* `ctaView`: The call to action view.

Example:

{% tabs %}
{% tab title="Swift" %}

```swift
nativeAd.attachToView(nativeAdContainerView,
                      mainImageView: adMainImageView,
                      iconView: adIconImageView,
                      ctaView: adCTALabel)
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
[self.nativeAd attachToView:self.containerView
              mainImageView:self.mainImageView
                    iconView:self.iconImageView
                    ctaView:self.ctaLabel];
```

{% endtab %}
{% endtabs %}

Also, you **must** remove the tracking view from the native ad, when the native ad isn't needed anymore or is replaced.

{% tabs %}
{% tab title="Swift" %}

```swift
nativeAd.detachFromLayout()
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
[self.nativeAd detachFromLayout];
```

{% endtab %}
{% endtabs %}

### Complete Code Example

{% tabs %}
{% tab title="Swift" %}

```swift
class ViewController: UIViewController {
    // Create the placement
    var placement = AATSDK.createNativeAdPlacement(name: "<PLACEMENT_NAME>", supportsMainImage: true)
    
    // Outlets
    @IBOutlet weak var containerView: UIView!
    @IBOutlet weak var adTitleLabel: UILabel!
    @IBOutlet weak var descriptionLabel: UILabel!
    @IBOutlet weak var adIconImageView: UIImageView!
    @IBOutlet weak var adMainImageView: UIImageView!
    @IBOutlet weak var advertiserLabel: UILabel!
    @IBOutlet weak var adCTALabel: UILabel!
    @IBOutlet weak var ratingLabel: UILabel!
 
    override func viewDidAppear(_ animated: Bool) {
        super.viewDidAppear(animated)
        
        // [IMPORTANT] Notify AATKit about the currently active view controller
        AATSDK.controllerViewDidAppear(controller: self)
        
        // Set placement delegate to listen to the callbacks
        placement.delegate = self
        
        // Request a native ad
        placement.reload()
    }
    
    override func viewWillDisappear(_ animated: Bool) {
        super.viewWillDisappear(animated)
        // [IMPORTANT] Remove the currently active view controller
        AATSDK.controllerViewWillDisappear()
    }
}

// MARK: - AATNativePlacementDelegate
extension ViewController: AATNativePlacementDelegate {
    func aatHaveAd(placement: AATPlacement) {
        // The placement has loaded a new ad
        guard let nativeAd = placement?.getNativeAd() else {
            return
        }
        // Assign the tracking view
        nativeAd.attachToView(containerView,
                              mainImageView: adMainImageView,
                              iconView: adIconImageView,
                              ctaView: adCTALabel)
        // Report Ad Space
        placement.reportAdSpace()
        // Ad Title
        adTitleLabel.text = nativeAd.title
        // Ad Body
	descriptionLabel.text = nativeAd.adDescription ?? "-"
        // Ad Icon
	loadImage(for: adIconImageView, imageUrlString: nativeAd.iconUrl)
        // Ad Main Image
        loadImage(for: adMainImageView, imageUrlString: nativeAd.imageUrl)
        // Ad Advertiser
        advertiserLabel.text = nativeAd.advertiser ?? "-"
        // Ad CTA Title
        adCTALabel.text = nativeAd.callToAction ?? "-"
        // Ad Rating
        if let rating = nativeAd.rating {
            self.ratingLabel.text = "\(rating.value)/\(rating.scale)"
        }
    }

    func aatNoAd(placement: AATPlacement) {
        // The placement could not load a new ad
    }
    
    func aatPauseForAd(placement: AATPlacement) {
        // Ad has been displayed on the screen
    }

    func aatResumeAfterAd(placement: AATPlacement) {
        // Back to the app after clicking on the ad
    }
}

// MARK: - Downloading Images
extension ViewController {
    func loadImage(for imageView: UIImageView, imageUrlString: String?) {
        guard let urlString = imageUrlString,
              let url = URL(string: urlString) else {
            return
        }
        DispatchQueue.global().async {
            guard let data = try? Data(contentsOf: url),
                let image = UIImage(data: data) else {
                return
            }
            DispatchQueue.main.async {
                imageView.image = image
            }
        }
    }
}
```

{% endtab %}

{% tab title="Objective-C" %}

```objectivec
@interface ViewController () <AATNativePlacementDelegate>
@property id<AATNativeAdPlacement> placement;
// Outlets
@property (weak, nonatomic) IBOutlet UIView *containerView;
@property (weak, nonatomic) IBOutlet UILabel *titleLabel;
@property (weak, nonatomic) IBOutlet UIImageView *mainImageView;
@property (weak, nonatomic) IBOutlet UIImageView *iconImageView;
@property (weak, nonatomic) IBOutlet UILabel *descriptionLabel;
@property (weak, nonatomic) IBOutlet UILabel *advertiserLabel;
@property (weak, nonatomic) IBOutlet UILabel *ctaLabel;
@end

@implementation ViewController
- (void)viewDidAppear:(BOOL)animated {
    [super viewDidAppear:animated];
    
    // [IMPORTANT] Notify AATKit about the currently active view controller
    [AATSDK controllerViewDidAppearWithController:self];
    
    // Create the placement
    self.placement = [AATSDK createNativeAdPlacementWithName:@"<PLACEMENT_NAME>" supportsMainImage:YES];
    
    // Set placement delegate to listen to the callbacks
    self.placement.delegate = self;
    
    // Request a native ad
    [self.placement reload];
}

- (void)viewWillDisappear:(BOOL)animated {
    [super viewWillDisappear:animated];
    // [IMPORTANT] Remove the currently active view controller
    [AATSDK controllerViewWillDisappear];
}

#pragma mark - AATNativePlacementDelegate
- (void)aatHaveAdWithPlacement:(id<AATPlacement>)placement {
    // The placement has loaded a new ad
    id<AATNativeAdData> nativeAd = [self.nativeAdPlacement getNativeAd];
    if (nativeAd) {
        [self.placement reportAdSpace];
        // Assign the tracking view
        [self.nativeAd attachToView:self.containerView
                      mainImageView:self.mainImageView
                           iconView:self.iconImageView
                            ctaView:self.ctaLabel];
        // Binding Data
        self.titleLabel.text = self.nativeAd.title;
        [self loadImage:self.iconImageView urlString:self.nativeAd.iconUrl];
        [self loadImage:self.mainImageView urlString:self.nativeAd.imageUrl];
        self.descriptionLabel.text = self.nativeAd.adDescription;
        self.advertiserLabel.text = self.nativeAd.advertiser;
        self.ctaLabel.text = self.nativeAd.callToAction;
        // Rating
        if (self.nativeAd.rating != nil) {
            self.ratingLabel.text = [NSString stringWithFormat:@"%d/%d", self.nativeAd.rating.value, self.nativeAd.rating.value];
        }
    }
}

- (void)aatNoAdWithPlacement:(id<AATPlacement>)placement {
    // The placement could not load a new ad
}

- (void)aatPauseForAdWithPlacement:(id<AATPlacement>)placement {
    // Ad has been displayed on the screen
}

- (void)aatResumeAfterAdWithPlacement:(id<AATPlacement>)placement {
    // Back to the app after clicking on the ad
}

#pragma mark - Downloading Images
- (void)loadImage:(UIImageView *)imageView urlString:(NSString *)urlString {
    NSURL *url = [NSURL URLWithString:urlString];
    NSData * imageData = [[NSData alloc] initWithContentsOfURL:url];
    imageView.image = [UIImage imageWithData:imageData];
}
@end
```

{% endtab %}
{% endtabs %}