Implement the pop-up window and PiP features

Pop-up window

A pop-up window is a floating window in Android that appears on the top of other apps. You can drag, resize, or close a pop-up window to manage the pop-up window. In most cases, pop-up windows are used to send reminders, notifications, and ads.

• In Android, each window corresponds to a Window object. A pop-up window is a special window that is implemented by using the PopupWindow class in ViewSystem.

• The PopupWindow class inherits motion capabilities from the WindowManager.LayoutParams class. This allows you to manage the position, size, and display mode of pop-up windows. You can also use the PopupWindow class to customize a pop-up window that is independent of activities and does not affect other apps.

Procedure

1. Declare the permissions on pop-up windows in the AndroidManifest.xml file.

   <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />

2. In the activity or service that needs to display a pop-up window, create a WindowManager instance and a PopupWindow object to configure attributes such as the display position, size, and content of the pop-up window.

   // Create a layout.
   View layout = View.inflate(this, R.layout.float_window, null);
   // Create a WindowManager instance.
   WindowManager wm = (WindowManager) this.getSystemService(Context.WINDOW_SERVICE);
   // Create a PopupWindow object.
   PopupWindow mPopupWindow = new PopupWindow(layout,
                                              WindowManager.LayoutParams.WRAP_CONTENT,
                                              WindowManager.LayoutParams.WRAP_CONTENT);
   // Configure the display position.
   mPopupWindow.showAtLocation(parentView, Gravity.LEFT | Gravity.TOP, x, y);
   // Configure the touchability and focusability.
   mPopupWindow.setTouchable(true);
   mPopupWindow.setFocusable(true);
   // Configure the background color.
   mPopupWindow.setBackgroundDrawable(new ColorDrawable(Color.TRANSPARENT));

3. Configure a callback for the events of controls in the pop-up window, such as touch and drag events.

   mPopupWindow.setOnTouchListener(new View.OnTouchListener() {
       int lastX, lastY;
       int paramX, paramY;
   
       @Override
       public boolean onTouch(View v, MotionEvent event) {
           // Obtain the coordinates of the current touch point on the screen.
           int x = (int) event.getRawX();
           int y = (int) event.getRawY();
           switch (event.getAction()) {
               case MotionEvent.ACTION_DOWN:
                   lastX = x;
                   lastY = y;
                   paramX = mPopupWindow.getLayoutParams().x;
                   paramY = mPopupWindow.getLayoutParams().y;
                   break;
               case MotionEvent.ACTION_MOVE:
                   int dx = x - lastX;
                   int dy = y - lastY;
                   mPopupWindow.update(paramX + dx, paramY + dy, -1, -1);
                   break;
           }
           return false;
       }
   });

   Important

   In Android 6.0 and later, you must dynamically apply for the permissions on pop-up windows. However, pop-up windows are still not supported on some devices that run Android 8.0.

PiP

• In Android 8.0 (API level 26) and later, Android allows activities to launch in PiP mode. PiP is a special multi-window mode that is mostly used for video playback. In PiP mode, users can watch a video in a small window pinned to a corner of the screen while they navigate between apps or browse on the home screen.

• PiP uses the multi-window methods made available in Android 7.0 to provide the pinned video overlay window. To add PiP to your app, you must register your activity that supports PiP and switch the activity to the PiP mode as needed. You must also make sure that user interface (UI) elements are hidden and video playback continues when the activity is in PiP mode.

• The PiP window appears at the topmost layer of the screen, in a corner that is chosen by the system.

• For more information, see Add videos using picture-in-picture (PiP).

Procedure

1. Declare that your activity supports PiP in the AndroidManifest.xml file.

   <Activity android:name="VideoActivity"
     android:supportsPictureInPicture="true"
     android:configChanges=
     "screenSize|smallestScreenSize|screenLayout|orientation"
     ...

   • By default, Android does not automatically support PiP for apps. If you want to add PiP to your app, register your activity in the AndroidManifest.xml file by setting the android:supportsPictureInPicture attribute to true.

   • In addition, specify that the activity handles layout configuration changes. This way, the activity does not relaunch if a layout configuration changes during PiP mode transitions. This ensures smooth user experience.

     Important

     PiP may be disabled on devices that have low random access memory (RAM). Before your app uses PiP, call the hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE) method to check whether PiP is available.

2. Switch the activity to the PiP mode.

   You can switch the activity to the PiP mode in one of the following ways:

   • Tap an icon on the app UI.

     Call a method such as onClicked(View) or onOptionsItemSelected(MenuItem).

     @Override
     public void onActionClicked(Action action) {
         if (action.getId() == R.id.lb_control_picture_in_picture) {
         	// Tap an icon on the app UI.
             enterPictureInPictureMode();
             return;
         }
         ...
     }

   • Exit the app. For example, tap the Home icon.

     onUserLeaveHint()

     To enter the PiP mode, the activity must call the enterPictureInPictureMode() method. For example, if users tap the Home or Recent Apps icon, the onUserLeaveHint() method is overridden to automatically switch the activity to the PiP mode.

     @Override
     public void onUserLeaveHint () {
         // Exit the app.
         if (iWantToBeInPipModeNow()) {
             enterPictureInPictureMode();
         }
     }

   • Tap the Return icon.

     onBackPressed()

     @Override
     public void onBackPressed() {
         super.onBackPressed();
         // Tap the Return icon.
         enterPictureInPictureMode();
     }

3. Handle UI elements in PiP mode.

   When your activity enters or exits the PiP mode, the system calls the Activity.onPictureInPictureModeChanged() or Fragment.onPictureInPictureModeChanged() method.

   You must override these methods to redraw the UI elements of the activity. Take note that your activity is displayed in a small window in PiP mode. Users may not be able to interact with the UI elements of your app in PiP mode, and the details of small UI elements may be difficult to see. Video playback activities with minimal UI elements provide optimal user experience.

   1. Implement a much smoother animation when the activity exits the PiP mode.

      When the activity exits the PiP mode, you can add an animation to improve the smoothness and visual effects of the exit transition.

   2. Add controls.

      In PiP mode, users may not be able to interact with the UI elements of your app. Therefore, you can consider adding some simple controls in the PiP window so that users can perform basic operations, such as play, pause, previous, and next.

   3. Disable seamless resizing for non-video content.

      In PiP mode, seamless resizing is enabled to display video content at an appropriate aspect ratio and ensure that the video image is not stretched or cropped. However, for non-video content, such as text and images, seamless resizing may need to be disabled to prevent the content from becoming unreadable or distorted in the small PiP window. After seamless resizing is disabled, non-video content can maintain good visibility and operability in PiP mode.

4. Continue video playback in PiP mode.

   When your activity enters the PiP mode, the system pauses the activity and calls the onPause() method on the activity. However, video playback must continue but cannot be paused if the activity is paused in PiP mode.

   In Android 7.0 and later, the following logic is implemented:

   • When the system calls the onStop() method on the activity, video playback is paused.

   • When the system calls the onStart() method on the activity, video playback is resumed.

   This way, you do not need to check whether your app is in PiP mode by calling the onPause() method and video playback can continue.

   If you need to pause video playback by calling the onPause() method, call the isInPictureInPictureMode() method to check whether your app is in PiP mode and handle video playback appropriately. The following sample code provides an example:

   @Override
   public void onPause() {
       // If called while in PiP mode, do not pause playback
       if (isInPictureInPictureMode()) {
           // Continue playback
           ...
       } else {
           // Use existing playback logic for paused Activity behavior.
           ...
       }
   }

Pop-up window

In iOS, you can use the UIWindow class to create a window and add the view of a video player to the window. You can use gestures to adjust the position and size of the window. This implements the PiP effects of a pop-up window.

PiP

The PiP feature is supported in iOS 9 and later. However, the PiP feature is previously available only on iPads. In iOS 14 and later, iPhone users can use the PiP feature.

iOS provides the following two solutions to help you implement the PiP feature:

1. Old solution for devices that run iOS 14 or later

   

   In iOS 14, you can use the AVPlayer class to initialize an AVPictureInPictureController object. This way, you can implement the PiP feature if users switch your app to the background or go to secondary pages. This solution is applicable if you do not have high requirements for a player.

2. New solution for devices that run iOS 15 or later

   

   In iOS 15 and later, you can use the AVSampleBufferDisplayLayer class to create an AVPictureInPictureController object for seamless video playback in PiP mode. This solution is applicable if you want to implement the PiP feature for a custom player. ApsaraVideo Player SDK provides the PiP feature. For more information, see the Configure PiP section of the "Advanced features" topic.

Procedure

The procedures for implementing the PiP feature are similar in the old and new solutions. This section describes how to implement the PiP feature by using the old solution.

1. Enable the background mode.

   

2. Import the framework: #import <AVKit/AVKit.h>. Create an AVPictureInPictureController object.

   // 1. Check whether the PiP feature is supported.
   if ([AVPictureInPictureController isPictureInPictureSupported]) {
       // 2. Configure permissions.
       @try {
           NSError *error = nil;
           [[AVAudioSession sharedInstance] setCategory:AVAudioSessionOrientationBack error:&error];
           [[AVAudioSession sharedInstance] setActive:YES error:&error];
       } @catch (NSException *exception) {
           NSLog(@"AVAudioSession error");
       }
       self.pipVC = [[AVPictureInPictureController alloc] initWithPlayerLayer:self.player];
       self.pipVC.delegate = self;
   }

3. Enable or disable the PiP feature.

   if (self.pipVC.isPictureInPictureActive) {
       [self.pipVC stopPictureInPicture];
   } else {
       [self.pipVC startPictureInPicture];
   }

4. Configure a delegate for the AVPictureInPictureController object.

   // Video playback in PiP mode is about to start.
   - (void)pictureInPictureControllerWillStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController;
   // Video playback in PiP mode is started.
   - (void)pictureInPictureControllerDidStartPictureInPicture:(AVPictureInPictureController *)pictureInPictureController;
   // Failed to start video playback in PiP mode.
   - (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController failedToStartPictureInPictureWithError:(NSError *)error;
   // Video playback in PiP mode is about to stop.
   - (void)pictureInPictureControllerWillStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController;
   // Video playback in PiP mode is stopped.
   - (void)pictureInPictureControllerDidStopPictureInPicture:(AVPictureInPictureController *)pictureInPictureController;
   // Video playback is resumed in the player window.
   - (void)pictureInPictureController:(AVPictureInPictureController *)pictureInPictureController restoreUserInterfaceForPictureInPictureStopWithCompletionHandler:(void (^)(BOOL restored))completionHandler;

   Important

   1. You can use the global variable pictureInPictureController to manage the PiP controller. If the pictureInPictureControllerWillStartPictureInPicture method is called, the PiP controller is initialized. If the pictureInPictureControllerDidStopPictureInPicture method is called, the PiP controller is destroyed.

   2. If the PiP controller is not started by using the PiP icon, you can call the viewWillAppear method to monitor and stop the PiP controller.

   3. If a PiP window already exists and you want to open another PiP window, you must wait until the existing PiP window is closed. This prevents unknown errors because it takes time to close a PiP window.

   4. If you create an AVPictureInPictureController object and enable the PiP feature at the same time, a failure may occur. In this case, we recommend that you enable the PiP feature later.