Page Contents

    Error Handling with the Native SDK for iOS

    In this topic, you will learn how the Brightcove Native SDK for iOS handles playback errors.

    Overview

    Error codes have the term ErrorCode in the name. For example:

    kBCOVPlaybackSessionErrorCodeLoadFailed

    Events have the word Event in the name. For example:

    kBCOVPlaybackSessionLifecycleEventFail

    Playback errors

    Playback errors are handled through events. Generally speaking you would receive playback errors using the lifecycle event delegate callback on the BCOVPlaybackController:

    - (void)playbackSession:(id<BCOVPlaybackSession>)session
      didReceiveLifecycleEvent:(BCOVPlaybackSessionLifecycleEvent *)lifecycleEvent

    To get further information, do the following:

    1. If you get an error event like kBCOVPlaybackSessionLifecycleEventFail or kBCOVPlaybackSessionLifecycleEventResumeFail, check the event's properties dictionary for an @"error" key.

      This will provide an NSError object with information about the problem.

    2. Each NSError will have an error domain, like the following:

      • NSCocoaErrorDomain
      • kBCOVPlaybackSessionErrorDomain
       

      Each error domain will have an associated error code and error description, like the following:

      • kBCOVPlaybackSessionErrorCodeLoadFailed
      • kBCOVPlaybackSessionErrorCodeNoPlayableSource
    3. Some errors will also have an underlying error that can be retrieved from the error object's userInfo dictionary with the NSUnderlyingErrorKey key. This will typically be a system NSError that can provide more information.

    4. To find all the error domains in the SDK, search the headers for the following:

      ErrorDomain

      Here is a list of headers that have ErrorDomain references:

      • BCOVFPSAuthorizationProxy.h
      • BCOVFPSBrightcoveAuthProxy.h
      • BCOVOfflineVideoManager.h
      • BCOVPlaybackService.h
      • BCOVPlaybackSession.h
    5. To find all the error codes, search each ErrorDomain for the following:

      ErrorCode

      For example, in BCOVPlaybackSession.h, you'll see kBCOVPlaybackSessionErrorDomain with the following error codes:

      • kBCOVPlaybackSessionErrorCodeLoadFailed
      • kBCOVPlaybackSessionErrorCodeFailedToPlayToEnd
      • kBCOVPlaybackSessionErrorCodeNoPlayableSource
    6. Other domains may return errors differently. For example, the BCOVPlaybackService object will return errors in its completion blocks if there are network errors when requesting videos from the online catalog. It uses the error domain kBCOVPlaybackServiceErrorDomain.

    Playback errors table

    Here is a list of possible playback errors from the Native SDK for iOS. Be aware that errors can also be passed through from the underlying framework.

    iOS playback errors
    Header Error Description
    BCOVFPSAuthorizationProxy.h kBCOVFPSErrorDomain Error domain for FairPlay related errors
    kBCOVFPSErrorCodeStreamingContentKeyRequest Error occured requesting content key
    kBCOVFPSErrorCodeApplicationCertificateRequest Error occured requesting application certificate
    BCOVFPSBrightcoveAuthProxy.h kBCOVFPSAuthProxyErrorDomain Error domain for FairPlay Auth Proxy related errors.
    kBCOVFPSAuthProxyErrorCodeApplicationCertificateRequestFailed Request for Application Certificate failed
    kBCOVFPSAuthProxyErrorCodeContentKeyRequestFailed Request for Key failed
    kBCOVFPSAuthProxyErrorCodeContentKeyGenerationFailed Key request generation failed
    BCOVPlaybackService.h BCOVPlaybackServiceErrorNoError No error.
    BCOVPlaybackServiceErrorCodeConnectionError Error Code that indicates there was an error connecting to the Playback API. Check the error.userInfo key NSUnderlyingErrorKey for the actual connection error.
    BCOVPlaybackServiceErrorCodeJSONDeserializationError Error Code that indicates there was an error parsing the response as JSON. If the request returned any data, that raw NSData will be included in the userInfo by key kBCOVPlaybackServiceErrorKeyRawResponseData. Check the error.userInfo key NSUnderlyingErrorKey for the actual JSON deserialization error.
    BCOVPlaybackServiceErrorCodeAPIError Error Code that indicates there was an error returned by the API. Check the error.userInfo key kBCOVPlaybackServiceErrorKeyAPIErrors for an NSArray of errors returned by the API and key kBCOVPlaybackServiceErrorKeyAPIHTTPStatusCode to find the status code returned.
    kBCOVPlaybackServiceErrorDomain Error domain for BCOVPlaybackService.
    kBCOVPlaybackServiceErrorKeyRawResponseData Key for NSError.userInfo for errors with domain kBCOVPlaybackServiceErrorDomain and errorCode BCOVPlaybackServiceErrorCodeJSONDeserializationError. This is the raw response data. This may not exist in error.userInfo.
    kBCOVPlaybackServiceErrorKeyAPIErrors Key for NSError.userInfo for errors with domain kBCOVPlaybackServiceErrorDomain and errorCode BCOVPlaybackServiceErrorCodeAPIError. This is an NSArray of errors returned by the Playback API.
    kBCOVPlaybackServiceErrorKeyAPIHTTPStatusCode Key for NSError.userInfo for errors with domain kBCOVPlaybackServiceErrorDomain and errorCode BCOVPlaybackServiceErrorCodeAPIError. This is the HTTP status code returned by the API request.
    BCOVPlaybackSession.h kBCOVPlaybackSessionEventKeyError The video failed to load. The event properties will contain the underlying error.
    kBCOVPlaybackSessionLifecycleEventFailedToPlayToEndTime

    The video failed during playback and was unable to recover, possibly due to a network error. The event properties will contain the underlying error keyed by kBCOVPlaybackSessionEventKeyError

    It may be possible to recover from this error once the network has recovered, by using the [BCOVPlaybackController resumeVideoAtTime:withAutoPlay:] method.

    kBCOVPlaybackSessionEventKeyError A generic error has occurred. The event properties may contain the underlying
    kBCOVPlaybackSessionLifecycleEventThumbnailAssetFailedToLoad The thumbnail seeking asset failed to load. The event properties may contain the underlying error keyed by kBCOVPlaybackSessionEventKeyError.
    kBCOVPlaybackSessionEventKeyError The key for the error in the Event properties.
    kBCOVPlaybackSessionErrorDomain Error domain for the SDK.
    kBCOVPlaybackSessionErrorCodeLoadFailed The video failed to load.
    kBCOVPlaybackSessionErrorCodeFailedToPlayToEnd The video failed during playback and was unable to recover, possibly due to a network error.
    kBCOVPlaybackSessionErrorCodeNoPlayableSource No playable Source was available for this Video.
    kBCOVPlaybackSessionErrorCodeWifiUnavailable No WiFi network is available and allowsCellularPlayback is disabled.

    Page last updated on 22 Jul 2022