This topic describes the exceptions and special scenarios that you may encounter when you use Push SDK for iOS. This topic also describes how to handle such exceptions and special scenarios.

Handle AlivcLivePusherErrorDelegate callbacks

  • When you receive an onSystemError callback message, which indicates a system error, stop live streaming.
  • When you receive an onSDKError callback message, which indicates an SDK error, destroy the current AlivcLivePusher object and then create another one. Alternatively, you can call the restartPush or restartPushAsync operation to restart the current AlivcLivePusher object.
  • You must pay special attention to the callbacks that are related to microphone and camera permissions. The 268455940 error code indicates that the mobile app requires permissions to use the microphone. The 268455939 error code indicates that the mobile app requires permissions to use the camera.

Handle AlivcLivePusherNetworkDelegate callbacks

  • An onNetworkPoor callback message is sent to you when the network speed is slow. The message indicates that the network conditions can no longer support stream ingest, but the stream is still being ingested and not interrupted. When the network conditions return to normal, an onNetworkRecovery callback message is sent to you. At this point, you can configure custom business logic. For example, you can notify your users of network recovery on the mobile app UI.
  • The onConnectFail, onReconnectError, or onSendDataTimeout callback is returned when a specific network error occurs. In this case, destroy the current AlivcLivePusher object and then create another one. Alternatively, you can call the reconnectAsync operation to reconnect to the network. We recommend that you test the network connectivity and the ingest URL before you perform the reconnection operation.
  • The SDK fires the onReconnectStart callback to reconnect to the network when the SDK receives a reconnection request. The reconnection request may be issued by the SDK or the developer that calls the reconnectAsync operation. To reconnect to the network, the mobile app reinitiates a connection to the Real-Time Messaging Protocol (RTMP) server.

    After the RTMP connection is established, an onReconnectSuccess callback message is sent to you. However, the message does not mean that the mobile app resumes stream ingest. Stream ingest may fail to be resumed if network issues persist. In this case, the SDK keeps reconnecting to the RTMP server.

  • An onPushURLAuthenticationOverdue callback message indicates the expiration of the ingest URL authentication. The SDK sends such a message to you only after you enable ingest URL authentication. An ingest URL contains the auth_key field. This callback is fired 1 minute before the ingest URL expires. After you receive such a message, you must specify a new ingest URL to ensure that the ingest process is not interrupted due to the expiration of the original ingest URL. Sample code:
    - (NSString *)onPushURLAuthenticationOverdue:(AlivcLivePusher *)pusher {
    return @"New ingest URL rtmp://";
    }

Handle AlivcLivePusherBGMDelegate callbacks

  • The onOpenFailed callback is fired when the background music (BGM) fails to be played. In this case, check whether the audio file and the file path specified for the startBGMAsync operation are valid. Then, call the startBGMAsync operation to replay the BGM.
  • The onDownloadTimeout callback is fired when the BGM playback times out. This issue generally occurs when the BGM is specified by using an online URL. This callback instructs the streamer to check the status of the network. You can call the startBGMAsync operation to replay the BGM.

Handle network disconnection

  • Short-period network disconnection and network switchover: The SDK attempts to reconnect to the network when a network fluctuation or a network switchover occurs. You can call the AlivcLivePushConfig operation to set the reconnection timeout period and the maximum number of reconnection attempts allowed. After the SDK reconnects to the network, stream ingest is resumed. If you use ApsaraVideo Player, we recommend that you perform a reconnection operation 5 seconds after you receive an AliVcMediaPlayerPlaybackDidFinishNotification timeout notification.
  • Long-period network disconnection: The SDK fails to reconnect to the network if a reconnection request times out or the number of reconnection attempts exceeds the upper limit. In this case, the onReconnectError:error: callback is fired. After the network is recovered, call the reconnectAsync operation to reconnect the SDK to the network. You must also reconnect the SDK to ApsaraVideo Player.
    • We recommend that you externally monitor the network.
    • Use the server to handle communication failures between the streamer and player. For example, when the streamer disconnects from the server, the server receives a callback message of stream ingest interruption from Alibaba Cloud CDN. The server pushes the callback message to the player. Then, the player takes the relevant measures to handle the stream ingest interruption. The server uses the same procedure to resume stream ingest.
    • Stop and then restart ApsaraVideo Player to reconnect the player to the ingest URL. To achieve this, call the stop, prepare, and play operations in sequence.
      [self.mediaPlayer stop];
      AliVcMovieErrorCode err = [self.mediaPlayer prepareToPlay:[NSURL URLWithString:@"Streaming URL"]];
      if(err != ALIVC_SUCCESS) {
        NSLog(@"play failed,error code is %d",(int)err);
        return;
      }
      [self.mediaPlayer play];
      Note For more information about ApsaraVideo Player, see Implementation.

Switch the mobile app to the background or answer a phone call

The SDK provides built-in configurations for the background mode. When you switch the mobile app to the background, the video is paused at the last frame. The mobile app continues playing the audio in the background. Open your project in Xcode. On the Signing & Capabilities tab, select Audio, AirPlay, and Picture in Picture in the Background Mode section. This ensures that audio can be recorded when the mobile app is switched to the background. The following figure shows the configuration.Switch the mobile app to the background or answer a phone call
You can disable audio recording in the background to completely pause stream ingest when the mobile app is switched to the background. Stream ingest is resumed when the mobile app is switched back to the foreground. You can disable audio recording in the background by using one of the following methods:
  • Call the setMute operation to enable the mute mode when the mobile app is switched to the background. This method is recommended.
  • Call the stopPush operation to pause stream ingest when the mobile app is switched to the background and call the startPushWithURL or startPushWithURLAsync operation to resume stream ingest when the mobile app is switched back to the foreground.
    Note If you use this method, you must configure the system to monitor changes of the UIApplicationWillResignActiveNotification and UIApplicationDidBecomeActiveNotification properties. Otherwise, an error may occur.
    - (void)addNotifications {
    [[NSNotificationCenter defaultCenter] addObserver:self                                             
        selector:@selector(applicationWillResignActive:)                                             
        name:UIApplicationWillResignActiveNotification
        object:nil];
    [[NSNotificationCenter defaultCenter] addObserver:self
        selector:@selector(applicationDidBecomeActive:)
        name:UIApplicationDidBecomeActiveNotification                                      
        object:nil]; 
    }
     - (void)applicationWillResignActive:(NSNotification *)notification {
    [self.livePusher stopPush];
    }
     - (void)applicationDidBecomeActive:(NSNotification *)notification {
    [self.livePusher startPushWithURLAsync:pushURL];
    }

Play external audio

To play external audio on the page for stream ingest, we recommend that you use AVAudioPlayer because the SDK is incompatible with AudioServicesPlaySystemSound. After you configure external audio playback, you need to update the AVAudioSession settings. Sample code:
- (void)setupAudioPlayer {
   NSString *filePath = [[NSBundle
mainBundle] pathForResource:@"sound" ofType:@"wav"];
   NSURL *fileUrl = [NSURL URLWithString:filePath];
  self.player = [[AVAudioPlayer alloc] initWithContentsOfURL:fileUrl error:nil];
  self.player.volume = 1.0;
  [self.player prepareToPlay];
}
  - (void)playAudio {
    self.player.volume = 1.0;
    [self.player play];
// Configure AVAudioSession settings.
    AVAudioSession *session = [AVAudioSession sharedInstance];
    [session setMode:AVAudioSessionModeVideoChat error:nil];
    [session overrideOutputAudioPort:AVAudioSessionPortOverrideSpeaker error:nil];
    [session setCategory:AVAudioSessionCategoryPlayAndRecord withOptions:AVAudioSessionCategoryOptionDefaultToSpeaker|AVAudioSessionCategoryOptionAllowBluetooth
| AVAudioSessionCategoryOptionMixWithOthers error:nil];
    [session setActive:YES error:nil];
}

Change the size of the view during stream ingest

Check the values of the UIView properties when you call the startPreview or startPreviewAsync operation. Change the value of the frame property for all subviews in the preview. Sample code:
[self.livePusher startPreviewAsync:self.previewView];
for (UIView *subView in [self.previewView subviews]) {
  // ...
}

Adapt previews to an iPhone X

Generally, all previews can be properly displayed in full screen mode on mobile phones. However, the screen of an iPhone X has a special aspect ratio. Therefore, previews are distorted when they are displayed in full screen mode on an iPhone X. We recommend that you do not use preview in full screen mode on an iPhone X.

Set bitrates for ingested streams

The SDK supports dynamic bitrate conversion. You can call the AlivcLivePushConfig operation to change the default bitrate. Different services require different video quality. The resolution, smoothness, and definition of an output video vary based on the bitrate of the ingested stream.
  • Video definition: The larger the bitrate of the ingested stream is, the higher the video definition is. We recommend that you specify a large bitrate to ensure the playback of high-definition videos.
  • Video smoothness: The larger the bitrate of the ingested stream is, the higher the network bandwidth is required. A large bitrate with low network bandwidth may affect the smoothness of the videos.

Compilation error

When you receive a Building for iOS, but the linked and embedded framework XXX.framework' was built for iOS + iOS Simulator compilation error, perform the following operations:
  1. Click the Xcode menu.
  2. Choose File > Workspace Settings to enter dialog box settings.
  3. Change build System to Legacy build system.

Queen dependencies not found

In the case of manual integration, see the Queen_SDK_iOS documentation to add the corresponding dependencies.