RichieAds

Objective-C

@interface RichieAds : NSObject

Swift

class RichieAds : NSObject

RichieAds is the old main interface to Richie SDK’s ad system. You should look at RichieAdsController with new code.

NOTE: Many RichieAds methods are thread-safe, but their correct operation from the caller’s point of view requires them to be called from a single thread. Using RichieAds from main thread only is recommended. If slot ads are used, use from main thread is mandatory to ensure correct state observing from the client’s point of view.

-placeholderImageForAdWithIdentifier: methods are explicitly safe and good to be used from any thread. -viewForAdWithIdentifier: is explicitly main thread only.

Timing of calling -startLoadingAd and -containerWillBeDeleted may result in situations the caller didn’t intend or could not foresee, if multiple places of an app call these from multiple threads. Download state will change in a background thread, meaning calling -startLoadingAdWithIdentifier: and immediately calling -hasLoadedAdWithIdentifier: may return YES, in case an actual download wasn’t required (creative had been downloaded to another container).

It’s safe to manipulate a container from a single thread (preferably the main thread, which is used to post notifications). Even then state can be unexpected after calling -startLoadingAdWithIdentifier:. A supported and safe pattern is to use hasLoadedAdWithIdentifier: and then start loading the ad with -startLoadingAdWithIdentifier: if ad hasn’t been loaded. App should then wait for ad did load notification.

  • Undocumented

    Declaration

    Objective-C

    -(nonnull instancetype) initWithAppIdentifier:(nonnull NSString *)appIdentifier;

    Swift

    init(appIdentifier: String)

  • If you want to enable background downloads for ads, use this initializer. See RichieBackgroundDownloadManager for more information.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithAppIdentifier:(nonnull NSString *)appIdentifier
                    backgroundDownloadManager:
                        (nonnull RichieBackgroundDownloadManager *)
                            backgroundDownloadManager;

    Swift

    init(appIdentifier: String, backgroundDownloadManager: RichieBackgroundDownloadManager)

  • Unavailable

    Undocumented

    Declaration

    Objective-C

    -(nonnull instancetype) init NS_UNAVAILABLE;

  • This method should be called before relinquishing last reference to a RichieAds instance. It allows RichieAds to nicely shut down and clean up.

    Declaration

    Objective-C

    - (void)invalidate;

    Swift

    func invalidate()

  • Main thread only. Parameters dict (that must be encodable as JSON) is passed to the ad JavaScript when the ad is loaded. This is a way to pass app specific parameters to the ad.

    Declaration

    Objective-C

    - (nullable RichieAdsView *)viewWithFrame:(CGRect)frame
                             adIdentifier:(nonnull NSString *)adIdentifier
                             containerURL:(nonnull NSURL *)containerDir
                                 delegate:
                                     (nonnull id<RichieAdsViewDelegate>)delegate
                               parameters:(nullable NSDictionary *)parameters;

    Swift

    func view(withFrame frame: CGRect, adIdentifier: String, containerURL containerDir: URL, delegate: any RichieAdsViewDelegate, parameters: [AnyHashable : Any]?) -> RichieAdsView?

  • Thread-safe, reentrant.

    Returns an UIImage that can be drawn in place of loading the actual ad view. Use cases include thumbnails, previews etc. This is used internally by Richie Ads during HTML loading in the ad view.

    Ad must be successfully loaded before this method can be called.

    Callers must be prepared that this method may return nil, in case loading has encountered errors etc. A later invocation can return the image, if situation has been remedied.

    Declaration

    Objective-C

    - (nullable UIImage *)
    placeholderImageForAdWithIdentifier:(nonnull NSString *)adIdentifier
                          inOrientation:(RichieOrientation)orientation
                       withContainerURL:(nonnull NSURL *)containerDir;

    Swift

    func placeholderImageForAd(withIdentifier adIdentifier: String, in orientation: RichieOrientation, withContainerURL containerDir: URL) -> UIImage?

  • Returns correctly size and positioned rect for drawing image in targetRect. Drawing should be clipped to targetRect. This is useful when placeholder image has different aspect ratio than the view displaying placeholder image. For example, normal iPhone that displays thumbnails for giraffe iPhone ads.

    Declaration

    Objective-C

    - (CGRect)rectForDrawingPlaceholderImage:(nonnull UIImage *)image
                                  inRect:(CGRect)targetRect;

    Swift

    func rect(forDrawingPlaceholderImage image: UIImage, in targetRect: CGRect) -> CGRect

  • Returns YES when ad with adIdentifier has been loaded to containerDir and is ready for display.

    Thread-safe, reentrant.

    NOTE: State changes on a background thread, see class documentation for more information.

    Declaration

    Objective-C

    - (BOOL)hasLoadedAdWithIdentifier:(nonnull NSString *)adIdentifier
                   toContainerDir:(nonnull NSURL *)containerDir;

    Swift

    func hasLoadedAd(withIdentifier adIdentifier: String, toContainerDir containerDir: URL) -> Bool

  • Loads a persistent ad with indentifier adIdentifier to container at given local path (which must exist). When completion block is called, ad is ready for presentation with viewWithFrame::adIdentifier:containerURL:delegate:parameters:.

    It’s safe to call this method multiple times, even when ad has been loaded. Complection callback will be called after loading completes, or when ad has been determined to already been loaded (which is very fast). Completion won’t ever be called during the execution of this method.

    If ad has already been loaded (to given container or to another container) progress block won’t be called.

    Use of this method and deleteAdWithIdentifier: / containerWillBeDeleted: from the main thread is suggested, because that way the completion block will not be called for ads deleted after download has begun (but before it has completed).

    Callback blocks are always called on the main thread.

    Declaration

    Objective-C

    - (void)loadAdWithIdentifier:(nonnull NSString *)adIdentifier
              toContainerDir:(nonnull NSURL *)containerDir
       useBackgroundDownload:(BOOL)useBackgroundDownload
                    progress:(void (^_Nullable)(int64_t, int64_t))progress
                  completion:
                      (void (^_Nonnull)(BOOL, NSError *_Nullable))completion;

    Swift

    func loadAd(withIdentifier adIdentifier: String, toContainerDir containerDir: URL, useBackgroundDownload: Bool, progress: ((Int64, Int64) -> Void)?) async throws -> Bool

  • Marks container dir as deleted. All ads loaded to that container become unpresentable. Freeing actual disk storage depends on other containers using the same ad creatives.

    Thread-safe, reentrant.

    Declaration

    Objective-C

    - (void)containerWillBeDeleted:(nonnull NSURL *)containerDir;

    Swift

    func containerWillBeDeleted(_ containerDir: URL)

  • Marks ad as deleted becoming unpresentable. Freeing actual disk storage depends on other containers using the same ad creative.

    Thread-safe, reentrant.

    Declaration

    Objective-C

    - (void)deleteAdWithIdentifier:(nonnull NSString *)adIdentifier
              inContainerAtURL:(nonnull NSURL *)containerDir;

    Swift

    func deleteAd(withIdentifier adIdentifier: String, inContainerAt containerDir: URL)

  • Global persisted parameters can be used by ad creatives (using JavaScript API) to query global state. This gives creatives the opportunity to communicate with each other, using simple string values. For example, one creative can set a value for a key when some action has been performed by the user, and then another creative can know that this event has occurred.

    Note

    Parameters are retained only for a limited duration. They will be cleaned after 30 days of unuse.

    Declaration

    Objective-C

    - (void)setGlobalPersistedParameter:(nullable NSString *)param
                             forKey:(nonnull NSString *)key;

    Swift

    func setGlobalPersistedParameter(_ param: String?, forKey key: String)

  • See

    @p -setGlobalPersistedParameter:forKey:

    Declaration

    Objective-C

    - (nullable NSString *)globalPersistedParameterForKey:(nonnull NSString *)key;

    Swift

    func globalPersistedParameter(forKey key: String) -> String?

  • Call this method as early as you wish RichieAds to begin updating slot list. Calling any of the other slot methods causes this to be called. This method should be called as early as possible, because it causes the slot information to be loaded from disk and calling the accessors will wait for the loading to be complete. Calling this method in -application:didFinishLaunchingWithOptions: is very much recommended, because from that point to the time you first need slots there might be enough time to load store slot information and new slot information from the Internet.

    Declaration

    Objective-C

    - (void)setUsesSlotAds;

    Swift

    func setUsesSlotAds()

  • This property controls if RichieAds should refresh slot information and download slot ads automatically. Automatic refresh and download happens at app launch and when is brought back to foreground. Default value is YES. Set this property to NO if you want to control the timing of slot refreshes, which can be initiated with the method -refreshSlotAds.

    Declaration

    Objective-C

    @property (nonatomic) BOOL automaticallyRefreshesSlotAds;

    Swift

    var automaticallyRefreshesSlotAds: Bool { get set }

  • Call this method to make RichieAds refresh slot information from server and download any necessary slot ads. This is only needed when you have set automaticSlotDownloads = NO. This allows you to control when RichieAds uses network, if you want to prioritize ad downloads to happen after your own content has been loaded, or you want to not load ads when the user is on a 3G network.

    Declaration

    Objective-C

    - (void)refreshSlotAds;

    Swift

    func refreshSlotAds()

  • Returns a RichieAdFlight when slot display logic indicates it’s time to show an ad. For example, this method might be called for each page view in an app, but it could return an instance once in three calls. Instances returned from this method must be either shown to the user or released as quickly as possible, when it is known that the flight will not be shown to the user. This allows internal counters and logic to reserve view counts, but return them back to the slot when a flight won’t be shown.

    Declaration

    Objective-C

    - (nullable RichieAdsSlotAdFlight *)nextFlightForSlotWithIdentifier:
    (nonnull NSString *)slotIdentifier;

    Swift

    func nextFlightForSlot(withIdentifier slotIdentifier: String) -> RichieAdsSlotAdFlight?

  • The way to create a RichieAdsView from a RichieAdFlight.

    Declaration

    Objective-C

    - (nullable RichieAdsView *)
    viewWithFrame:(CGRect)frame
      forAdFlight:(nonnull RichieAdsSlotAdFlight *)slotAdFlight
         delegate:(nonnull id<RichieAdsViewDelegate>)delegate
       parameters:(nullable NSDictionary<NSString *, NSString *> *)parameters;

    Swift

    func view(withFrame frame: CGRect, for slotAdFlight: RichieAdsSlotAdFlight, delegate: any RichieAdsViewDelegate, parameters: [String : String]?) -> RichieAdsView?

Deprecated

  • Deprecated

    adPackageURL is not used. New API doesn’t expose ad URLs anymore. Integrator shouldn’t need to know ad URLs.

    Thread-safe, reentrant.

    Declaration

    Objective-C

    - (BOOL)hasLoadedAdWithIdentifier:(nonnull NSString *)adIdentifier
                          fromURL:(nullable NSURL *)adPackageURL
                 toContainerAtURL:(nonnull NSURL *)containerURL;

    Swift

    func hasLoadedAd(withIdentifier adIdentifier: String, from adPackageURL: URL?, toContainerAt containerURL: URL) -> Bool

  • Deprecated

    adPackageURL is not used. New API doesn’t expose ad URLs anymore. Integrator shouldn’t need to know ad URLs. RichieAds will internally fetch the correct url for ad identifier based on app identifier. This may mean that loading some ads which has previously succeeded will now fail. It means the ad should’ve never worked. Analytics haven’t been properly logged for such ads. This has happened if there has not been an ad with the identifier for the app identifier. It has been an easy mistake to make, and now Richie Ads makes it painfully obvious that such a mistake has happened.

    Downloads of invalid ad identifiers will fail with error RichieAdsErrorDomain + kRichieAdsError_NoSuchAdCreativeError.

    Use the new block-based API for loading persisten tds.

    Notifications will be sent on the main thread. Thread-safe, reentrant. If there’s already ad with the adIdentifier in the container, but from another URL, the old package will be immediately deleted and new package will be downloaded.

    Declaration

    Objective-C

    - (void)startLoadingAdWithIdentifier:(nonnull NSString *)adIdentifier
                             fromURL:(nonnull NSURL *)url
                    toContainerAtURL:(nonnull NSURL *)containerURL;

    Swift

    func startLoadingAd(withIdentifier adIdentifier: String, from url: URL, toContainerAt containerURL: URL)

  • Deprecated

    Undocumented

    Declaration

    Objective-C

    -(void) startLoadingAdWithIdentifier:(nonnull NSString *)adIdentifier
							 fromURL:(nonnull NSURL *)url
					toContainerAtURL:(nonnull NSURL *)containerURL
			   useBackgroundDownload:(BOOL)useBackgroundDownload DEPRECATED_ATTRIBUTE;

    Swift

    func startLoadingAd(withIdentifier adIdentifier: String, from url: URL, toContainerAt containerURL: URL, useBackgroundDownload: Bool)