Documentation

logo

ImaginationOverflow Share Target for Android is an Unity plugin that allows your app to be the target of content shared by users on Android devices. The plugin automatically updates the android manifest with your desired configuration and its API consists on an event registration.

Info

The plugin only handles share target activations, it doesn't handle the share of your app/game content to other apps.

Integration

Integrating with the plugin is as simple as registering an event in order to get the information, and call a method to start retrieving the data. This is an asynchronous operation but the plugin ensures that all event handlers are run in the Unity main thread.

using ImaginationOverflow.ShareTarget;
using ImaginationOverflow.ShareTarget.Data;
....

void Awake()
{
    ShareTargetManager.Instance.ShareActivated += ShareActivated;
}

Info

Don't forget to unregister the event when on the OnDestroy Unity event, this will avoid any memory leaks on your apps/games.

In the event handler, you have access to all information about the shared content, this includes the type of share that was made (single or multiple), the mime type of the shared content, and access to the shared file or files.

private void ShareActivated(IShareInformation sharedInfo)
{
        //
        //  IShareInformation instances implement the dispose pattern to free all resources
        //
        using (sharedInfo)
        {
            //
            //  On basic text share the content is stored on the SharedText Property
            //
            if (sharedInfo.FileType.Equals("text/plain"))
            {
                Debug.Log(sharedInfo.SharedText);
            }
            //
            //  If the user only shared one file, show its metadata and read its content
            //
            else if (sharedInfo.IsMultipleShare == false)
            {
                var sharedFile = sharedInfo.SharedFile;

                Debug.Log("Shared File Name " + sharedFile.FileName);
                Debug.Log("Shared File Path " + sharedFile.Path);
                Debug.Log("Shared File Size " + sharedFile.Length);
                var fileContent = new StreamReader(sharedFile);
                //  Read file content
            }
            else
            {
                //
                //  The app/game received a multi file share, so process all files
                //
                foreach (var sharedFile in sharedInfo.SharedFiles)
                {
                    Debug.Log("Shared File Name " + sharedFile.FileName);
                    Debug.Log("Shared File Path " + sharedFile.Path);
                    Debug.Log("Shared File Size " + sharedFile.Length);
                    var fileContent = new StreamReader(sharedFile);
                    //  Read file content
                }
            }
        }
}

The IShareInformation interface describes the basic contract for the information received when a user shares content to your app/game:

/// <summary>
/// Represents shared information
/// </summary>
public interface IShareInformation : IDisposable
{
    /// <summary>
    /// True when the share activation included multiple files, false otherwise
    /// </summary>
    bool IsMultipleShare { get; }
    /// <summary>
    /// The mimetype of the shared files/text
    /// </summary>
    string FileType { get; }
    /// <summary>
    /// When FileType is text/plain, the shared content will be accessible via this property (e.g When users share a text message or a text selection)
    /// </summary>
    string SharedText { get; }
    /// <summary>
    /// On single file shares, this property contains the file content stream, this instance also contains the file Name, Path and Length.
    /// </summary>
    DetailedFileStream SharedFile { get; }
    /// <summary>
    /// On multiple file shares, this property will contain a list of all shared files
    /// </summary>
    List<DetailedFileStream> SharedFiles { get; }
}

Configuring the Plugin

The plugin configuration interface is under Window -> ImaginationOverflow -> Share Target for Android -> Configuration:

Config

On the Configuration Window, you can set up if your app/game wants to receive multiple files on one share, by toggling on and off the Receive Multiple.

You can configure the shares that you want to receive by configuring the Mime Type or the Custom file extension sections.

Info

For a list of valid mime types please refer to the IANA official registry of MIME media types.

You can also use a wildcard (*) to support a full category of mime types, just as we see in the configuration above where we want to receive all files that are on the text, image, and video categories. The last mime type configuration states that the app/game only wants to receive audio/ogg so no other audio files will be matched to activate the app besides the .ogg ones.

Tip

If your app/game can handle any file of any type, you only need to register one mimetype */*

Finally, the custom file section, allows you to register to receive shares from files with custom extensions, in the example above, the app/game would appear as an option when the user tries to share files that have the .mycustomextension and .myotherextension. (e.g file1.mycustomextension or file2.myotherextension).

Testing

The plugin includes a builtin testing window that allows you to test the integration without deploying your game to a device.

Editor

The debug window is accessible under Window -> ImaginationOverflow -> Share Target for Android -> Debug Config

The editor debug window allows you to test every possible scenario that the plugin supports regarding sharing to the app/game, in order to test you need to fill out the File Type and add at least one file or text content. The last requirement to test on the editor is that your app/game should be running after all the conditions are met the Debug button will be interactable and if already integrated your project with the Share Target plugin the ShareActivated event should trigger.

Config

Android

On an actual device, depending on the mime types that your app support, you can either use a file explorer or simply an app that shares the content that you expect to receive on your app/game after you press share your application should appear as an option on the native share dialog:

Config

The image above ilustrates exactly that case, on your testing your app icon and app name will appear instead of the Share Target plugin image and name.