ShareCompat

Added in 1.1.0

class ShareCompat

Extra helper functionality for sharing data between activities. ShareCompat provides functionality to extend the ACTION_SEND/ ACTION_SEND_MULTIPLE protocol and support retrieving more info about the activity that invoked a social sharing action. IntentBuilder provides helper functions for constructing a sharing intent that always includes data about the calling activity and app. This lets the called activity provide attribution for the app that shared content. Constructing an intent this way can be done in a method-chaining style. To obtain an IntentBuilder with info about your calling activity, use the static method from. IntentReader provides helper functions for parsing the defined extras within an ACTION_SEND or ACTION_SEND_MULTIPLE intent used to launch an activity. You can also obtain a Drawable for the caller's application icon and the application's localized label (the app's human-readable name). Social apps that enable sharing content are encouraged to use this information to call out the app that the content was shared from.

Summary

Nested types

IntentBuilder is a helper for constructing ACTION_SEND and ACTION_SEND_MULTIPLE sharing intents and starting activities to share content.

IntentReader is a helper for reading the data contained within a sharing (ACTION_SEND) Intent.

Constants
const String!
EXTRA_CALLING_ACTIVITY = "androidx.core.app.EXTRA_CALLING_ACTIVITY"

Intent extra that stores the ComponentName of the calling activity for an ACTION_SEND intent.
const String!
EXTRA_CALLING_ACTIVITY_INTEROP = "android.support.v4.app.EXTRA_CALLING_ACTIVITY"

Intent extra that stores the ComponentName of the calling activity for an ACTION_SEND intent.
const String!
EXTRA_CALLING_PACKAGE = "androidx.core.app.EXTRA_CALLING_PACKAGE"

Intent extra that stores the name of the calling package for an ACTION_SEND intent.
const String!
EXTRA_CALLING_PACKAGE_INTEROP = "android.support.v4.app.EXTRA_CALLING_PACKAGE"

Intent extra that stores the name of the calling package for an ACTION_SEND intent.

Public functions
java-static Unit

This function is deprecated.

Use the system sharesheet.
java-static Unit
configureMenuItem(
    menu: Menu,
    menuItemId: @IdRes Int,
    shareIntent: ShareCompat.IntentBuilder
)

This function is deprecated.

Use the system sharesheet.
java-static ComponentName?
getCallingActivity(calledActivity: Activity)

Retrieve the ComponentName of the activity that launched calledActivity from a share intent.
java-static String?
getCallingPackage(calledActivity: Activity)

Retrieve the name of the package that launched calledActivity from a share intent.

Constants

EXTRA_CALLING_ACTIVITY

Added in 1.1.0
const val EXTRA_CALLING_ACTIVITY = "androidx.core.app.EXTRA_CALLING_ACTIVITY": String!

Intent extra that stores the ComponentName of the calling activity for an ACTION_SEND intent. Instead of using this constant directly, consider using getCallingPackage or getCallingPackage.

EXTRA_CALLING_ACTIVITY_INTEROP

Added in 1.1.0
const val EXTRA_CALLING_ACTIVITY_INTEROP = "android.support.v4.app.EXTRA_CALLING_ACTIVITY": String!

Intent extra that stores the ComponentName of the calling activity for an ACTION_SEND intent. Note that this is only for interoperability between pre-1.0 AndroidX and AndroidX 1.1+ worlds. You are strongly encouraged to use getCallingPackage or getCallingPackage.

EXTRA_CALLING_PACKAGE

Added in 1.1.0
const val EXTRA_CALLING_PACKAGE = "androidx.core.app.EXTRA_CALLING_PACKAGE": String!

Intent extra that stores the name of the calling package for an ACTION_SEND intent. When an activity is started using startActivityForResult this is redundant info. (It is also provided by getCallingPackage.) Instead of using this constant directly, consider using getCallingPackage or getCallingPackage.

EXTRA_CALLING_PACKAGE_INTEROP

Added in 1.1.0
const val EXTRA_CALLING_PACKAGE_INTEROP = "android.support.v4.app.EXTRA_CALLING_PACKAGE": String!

Intent extra that stores the name of the calling package for an ACTION_SEND intent. When an activity is started using startActivityForResult this is redundant info. (It is also provided by getCallingPackage.) Note that this is only for interoperability between pre-1.0 AndroidX and AndroidX 1.1+ worlds. You are strongly encouraged to use getCallingPackage or getCallingPackage.

Public functions

configureMenuItem

Added in 1.1.0
Deprecated in 1.5.0
java-static fun configureMenuItem(item: MenuItem, shareIntent: ShareCompat.IntentBuilder): Unit

Configure a MenuItem to act as a sharing action.

This method will configure a ShareActionProvider to provide a more robust UI for selecting the target of the share. History will be tracked for each calling activity in a file named with the prefix ".sharecompat_" in the application's private data directory. If the application wishes to set this MenuItem to show as an action in the Action Bar it should use setShowAsAction to request that behavior in addition to calling this method.

During the calling activity's lifecycle, if data within the share intent must change the app should change that state in one of several ways:

  • Call invalidateOptionsMenu. If the app uses the Action Bar its menu will be recreated and rebuilt. If not, the activity will receive a call to onPrepareOptionsMenu the next time the user presses the menu key to open the options menu panel. The activity can then call configureMenuItem again with a new or altered IntentBuilder to reconfigure the share menu item.
  • Keep a reference to the MenuItem object for the share item once it has been created and call configureMenuItem to update the associated sharing intent as needed.
Parameters
item: MenuItem

MenuItem to configure for sharing
shareIntent: ShareCompat.IntentBuilder

IntentBuilder with data about the content to share

configureMenuItem

Added in 1.1.0
Deprecated in 1.5.0
java-static fun configureMenuItem(
    menu: Menu,
    menuItemId: @IdRes Int,
    shareIntent: ShareCompat.IntentBuilder
): Unit

Configure a menu item to act as a sharing action.

Parameters
menu: Menu

Menu containing the item to use for sharing
menuItemId: @IdRes Int

ID of the share item within menu
shareIntent: ShareCompat.IntentBuilder

IntentBuilder with data about the content to share
See also
configureMenuItem

getCallingActivity

Added in 1.1.0
java-static fun getCallingActivity(calledActivity: Activity): ComponentName?

Retrieve the ComponentName of the activity that launched calledActivity from a share intent. Apps that provide social sharing functionality can use this to provide attribution for the app that shared the content.

Note: This data may have been provided voluntarily by the calling application. As such it should not be trusted for accuracy in the context of security or verification.

Parameters
calledActivity: Activity

Current activity that was launched to share content
Returns
ComponentName?

ComponentName of the calling activity

getCallingPackage

Added in 1.1.0
java-static fun getCallingPackage(calledActivity: Activity): String?

Retrieve the name of the package that launched calledActivity from a share intent. Apps that provide social sharing functionality can use this to provide attribution for the app that shared the content.

Note: This data may have been provided voluntarily by the calling application. As such it should not be trusted for accuracy in the context of security or verification.

Parameters
calledActivity: Activity

Current activity that was launched to share content
Returns
String?

Name of the calling package