Adaptadores personalizados de iOS

Artículo
05/17/2024

Los adaptadores personalizados permiten que nuestro SDK llame a otro SDK instalado en el mismo dispositivo, normalmente para la mediación. En este documento se describe el código que debe escribir para crear sus propios adaptadores personalizados.

Nota:

Los protocolos descritos aquí son exactamente los que usamos para implementar nuestros propios adaptadores de mediación.

Banners

Para realizar llamadas de mediación a otro SDK para mostrar banners, debe implementar el ANCustomAdapterBanner protocolo. Este protocolo solo especifica un método: requestBannerAdWithSize. Este método controla la creación de instancias del SDK mediado y su uso para realizar solicitudes de anuncios. Debe desencadenar eventos desde el SDK mediado mediante una llamada a métodos delegados como didLoadBannerAd. Consulte los ejemplos siguientes para obtener más información.

requestBannerWithAdSize toma los argumentos siguientes:

size: tamaño de la vista de anuncios mediada.
rootViewController: controlador de la vista de anuncios mediada.
parameterString: cadena opaca opcional que se pasa desde el servidor, que se puede usar para definir parámetros específicos del SDK, como información de destino adicional. La codificación del contenido de esta cadena depende completamente de la implementación del adaptador del SDK de terceros. En otras palabras, el parámetro debe rellenarse con valores comprendidos por el servidor de anuncios del SDK de terceros.
idString: el identificador de la unidad de anuncios tal como lo entiende el servidor de anuncios del SDK de terceros. Se refiere a un lugar específico donde un anunciante puede mostrar anuncios en una aplicación móvil. Este identificador es opaco para nuestro SDK móvil; el contenido del identificador y su codificación están a la altura de la implementación del SDK de terceros.
targetingParameters: cualquier parámetro de segmentación de anuncios, como la edad, el sexo o la ubicación que quiera enviar al SDK mediado. Es responsable de enviar los parámetros del SDK mediados que puede comprender.

A continuación se muestra un adaptador de ejemplo que media un SDK ficticio de "Godzilla" para mostrar anuncios de banner. Para obtener más información sobre las devoluciones de llamada de este ejemplo, vea las secciones Devoluciones de llamada necesarias y Devoluciones de llamada opcionales a continuación.

@implementation GodzillaBannerAdaptor
@synthesize delegate;
#pragma mark GodzillaCustomAdapterBanner
- (void)requestBannerAdWithSize:(CGSize)size
             rootViewController:(UIViewController *)rootViewController
                serverParameter:(NSString *)parameterString
                       adUnitId:(NSString *)idString
            targetingParameters:(ANTargetingParameters *)targetingParameters
{
    // Here is where you are responsible for (1) instantiating the mediated SDK,
    // (2) building a request object using the elements of `targetingParameters`.
    // Note that you are responsible for ensuring that the targeting
    // parameters can be understood by the mediated SDK.  We also assume that (3)
    // you create a view in the mediated SDK that you can use to make the ad request.
    // Next, we tell the mediated SDK's ad view to request a banner ad from their ad
    // server.  If it works, we call the `didLoadBannerAd` method on our delegate to
    // notify it that we've successfully loaded an ad.
    [self.gzAdView getAdWithRequest:request onCompletion:^(BOOL success, NSError *error) {
        if (success) {
            [self.delegate didLoadBannerAd:self.gzAdView];
        } else {
    // If the mediated SDK was not able to load an ad successfully, we are responsible 
    // for translating the mediated SDK's error codes into something that we can 
    // understand and report to our delegate using `didFailToLoadAd`.
            ANAdResponseCode code = ANAdResponseInternalError;
            switch (error.code) {
                case GodzillaAdUnknownError:
                    code = ANAdResponseInternalError;
                    break;
                case GodzillaAdServerError:
                    code = ANAdResponseNetworkError;
                    break;
                case GodzillaAdUnavailable:
                    code = ANAdResponseUnableToFill;
                    break;
                case GodzillaAdDisabled:
                    code = ANAdResponseInvalidRequest;
                    break;
                default:
                    code = ANAdResponseInternalError;
                    break;
            }
            [self.delegate didFailToLoadAd:code];
        }
    }];
}
#pragma mark GodzillaBannerDelegate
// Implement the required callbacks that allow the mediated SDK to
// communicate with ours.
- (void)GodzillaAdWillPresent:(GodzillaBanner *)bannerAd {
    [self.delegate willPresentAd];
}
- (void)GodzillaAdDidPresent:(GodzillaBanner *)bannerAd {
    [self.delegate didPresentAd];
}
- (void)GodzillaAdWillDismiss:(GodzillaBanner *)bannerAd {
    [self.delegate willCloseAd];
}
- (void)GodzillaAdDidDismiss:(GodzillaBanner *)bannerAd {
    [self.delegate didCloseAd];
}
- (void)GodzillaAdDidInteract:(GodzillaBanner *)bannerAd {
    [self.delegate adWasClicked];
}
- (void)GodzillaAdWillLeaveApplication:(GodzillaBanner *)bannerAd {
    [self.delegate willLeaveApplication];
}

Interstitials

Para realizar llamadas de mediación a otro SDK para mostrar intersticiales, debe implementar el ANCustomAdapterInterstitial protocolo. Hay tres métodos especificados por este protocolo:

requestInterstitialAdWithParameter: solicita los anuncios intersticiales desde el SDK mediado. Toma tres argumentos:
- parameterString: cadena opaca opcional que se pasa desde el servidor, que se puede usar para definir parámetros específicos del SDK, como información de destino adicional. La codificación del contenido de esta cadena depende completamente de la implementación del adaptador del SDK de terceros. En otras palabras, el parámetro debe rellenarse con valores comprendidos por el servidor de anuncios del SDK de terceros.
- idString: el identificador de la unidad de anuncios tal como lo entiende el servidor de anuncios del SDK de terceros. Se refiere a un lugar específico donde un anunciante puede mostrar anuncios en una aplicación móvil. Este identificador es opaco para nuestro SDK móvil; el contenido del identificador y su codificación están a la altura de la implementación del SDK de terceros.
- targetingParameters: cualquier parámetro de segmentación de anuncios, como la edad, el sexo o la ubicación que quiera enviar al SDK mediado. Es responsable de enviar los parámetros del SDK mediados que puede comprender.
isReady: independientemente de si hay un anuncio intersticial cargado y listo para mostrarse al usuario.
presentFromViewController: muestra el anuncio intersticial al usuario. Debe incluir una comprobación para isReady ver si puede funcionar. Toma un argumento, viewController, que es el controlador de vista que se usa para mostrar el intersticial.

En este código de ejemplo, mediamos un SDK ficticio de "Godzilla" y hacemos que muestre un anuncio intersticial:

@implementation GodzillaInterstitialAdaptor
@synthesize delegate;
#pragma mark GodzillaCustomAdapterInterstitial
- (void)requestInterstitialAdWithParameter:(NSString *)parameterString
                                  adUnitId:(NSString *)idString
                       targetingParameters:(ANTargetingParameters *)targetingParameters
{
    // Here is where you are responsible for (1) instantiating the mediated SDK,
    // (2) building a request object using the elements of `targetingParameters`.
    // Note that you are responsible for ensuring that the targeting
    // parameters can be understood by the mediated SDK.  We also assume that (3)
    // you create a view in the mediated SDK that you can use to make the ad request.
    // Next, we tell the mediated SDK's ad view to request an interstitial ad from their
    // ad server.  If it works, we call the `didLoadInterstitialAd` method on our 
    // delegate to notify it that we've successfully loaded the ad.
    [GodzillaInterstitial fetchWithRequest:request
                          UUID:idString
                          onCompletion:^(BOOL success, NSError *error) {
                          if (success) {
                            [self.delegate didLoadInterstitialAd:self];
                          }
                          else {
    // If the mediated SDK was not able to load an ad successfully, we are responsible 
    // for translating the mediated SDK's error codes into something that we can 
    // understand and report to our delegate using `didFailToLoadAd`.
    ANAdResponseCode code = ANAdResponseInternalError;
    switch (error.code) {
                    case GodzillaAdUnknownError:
                        code = ANAdResponseInternalError;
                        break;
                    case GodzillaAdServerError:
                        code = ANAdResponseNetworkError;
                        break;
                    case GodzillaAdUnavailable:
                        code = ANAdResponseUnableToFill;
                        break;
                    case GodzillaAdDisabled:
                        code = ANAdResponseInvalidRequest;
                        break;
                    default:
                        code = ANAdResponseInternalError;
                        break;
                }
                [self.delegate didFailToLoadAd:code];
            }
        }];
}
- (void)presentFromViewController:(UIViewController *)viewController {
    // First, we check if the ad is not ready to show.  If true, we
    // fire the `failedToDisplayAd` event and exit.
    if (![self isReady]) {
        [self.delegate failedToDisplayAd];
        return;
    }
    // At this point, we know that an ad is ready.  We tell the
    // mediated interstitial view to show the ad, and if it fails,
    // we fire the `failedToDisplayAd` method.
    [GodzillaInterstitial displayfromViewController:viewController
                          onCompletion:^(BOOL success, NSError *error) {
                          if (!success) {
                              NSLog(@"Godzilla interstitial call to display ad failed");
                              [self.delegate failedToDisplayAd];
                          }
                      }];
}
- (BOOL)isReady {
    // Check whether the mediated SDK has an ad available to show.
    return [GodzillaInterstitial isReady];
}
#pragma mark GodzillaInterstitialDelegate
// Implement the required callbacks that allow the mediated SDK to
// communicate with ours.
- (void)GodzillaAdWillPresent:(GodzillaInterstitial *)interstitialAd {
    [self.delegate willPresentAd];
}
- (void)GodzillaAdDidPresent:(GodzillaInterstitial *)interstitialAd {
    [self.delegate didPresentAd];
}
- (void)GodzillaAdWillDismiss:(GodzillaInterstitial *)interstitialAd {
    [self.delegate willCloseAd];
}
- (void)GodzillaAdDidDismiss:(GodzillaInterstitial *)interstitialAd {
    [self.delegate didCloseAd];
}
- (void)GodzillaAdDidInteract:(GodzillaInterstitial *)interstitialAd {
    [self.delegate adWasClicked];
}
- (void)GodzillaAdWillLeaveApplication:(GodzillaInterstitial *)interstitialAd {
    [self.delegate willLeaveApplication];
}

Devoluciones de llamada necesarias

Las devoluciones de llamada que se enumeran a continuación deben implementarse en el adaptador personalizado. Puede ver ejemplos de su uso en los ejemplos de código de otra parte de esta página.

Para indicar una solicitud de anuncio correcta, llame a una de las siguientes opciones en función de si el anuncio es un banner o intersticial:

- (void)didLoadBannerAd:(UIView *)view: la solicitud de anuncio del SDK mediado se completó y devolvió un banner correctamente.
- (void)didLoadInterstitialAd:(id<ANCustomAdapterInterstitial>)adaptor: la solicitud de anuncio del SDK mediado se completó y devolvió una intersticial. Pase una referencia al adaptador actual.

Para indicar una solicitud de anuncio incorrecta si el anuncio es un banner o intersticial, llame a:

- (void)didFailToLoadAd:(ANAdResponseCode)errorCode: la solicitud de anuncio del SDK mediado no pudo devolver un anuncio válido.

Además, para los adaptadores intersticiales, un intento fallido de show() debe llamar a:

- (void)failedToDisplayAd: el SDK mediado recibió una llamada para presentar un elemento intersticial, pero no había ningún anuncio disponible o no se pudo presentar el SDK.

Devoluciones de llamada opcionales

Las devoluciones de llamada que se enumeran a continuación deben implementarse en adaptadores personalizados para banners e intersticiales. Tenga en cuenta que no son estrictamente necesarias.

- (void)adWasClicked: el usuario ha hecho clic en el anuncio mientras lo muestra el SDK mediado.
- (void)willPresentAd: el usuario interactúa con el anuncio y el SDK mediado está a punto de presentar una vista modal.
- (void)didPresentAd: el SDK mediado ha presentado la vista modal.
- (void)willCloseAd: el SDK mediado está a punto de cerrar la vista modal.
- (void)didCloseAd: el SDK mediado cierra la vista modal.
- (void)willLeaveApplication: el SDK mediado iniciará una aplicación externa.

Compartir a través de

Adaptadores personalizados de iOS

Banners

Interstitials

Devoluciones de llamada necesarias

Devoluciones de llamada opcionales

Recursos adicionales

Compartir a través de

Adaptadores personalizados de iOS

Banners

Interstitials

Devoluciones de llamada necesarias

Devoluciones de llamada opcionales

Temas relacionados

Recursos adicionales