Getting Started

Universal File Association plugin enables your Unity apps and games to be configured as the default file handler (e.g .xpto, .pdf) on iOS, Android, Windows 10 (UWP), Standalone (Linux, Mac, and Windows) and tvOS.

Using the Plugin¶

The plugin uses a single event where you need to register in order to receive file activations on all platforms:

void Start()
{
    ImaginationOverflow.UniversalFileAssociation.FileAssociationManager.Instance.FileActivated += FileActivatedHandler;
}

private void FileActivatedHandler(ImaginationOverflow.UniversalFileAssociation.Data.FileInformation s)
{
    //
    //  my activation code
    //
}

Never forget to remove your event registration when the GameObject where you registered it is destroyed:

void OnDestroy()
{
    ImaginationOverflow.UniversalFileAssociation.FileAssociationManager.Instance.FileActivated -= FileActivatedHandler;
}

The FileActivated event will be triggered when your game is started or resumed by a file activation.

The FileActivated event single argument FileInformation contains the filename, path, size, extension and a Stream of the activated file:

public class FileInformation
{
    public Stream Stream { get; set; }

    public string Path { get; set; }

    public string Name { get; set; }

    public string FileExtension { get; set; }

    public ulong Size { get; set; }
}

Consider the following example:

private void FileActivatedHandler(ImaginationOverflow.UniversalFileAssociation.Data.FileInformation fileActivated)
{
    var size = fileActivated.Size;
    var fileContent = new StreamReader(fileActivated.Stream).ReadToEnd();
    var fileName = fileActivated.Name;
}

The FileInformation class of an activated file contains a Stream that enables you to read the complete file content. In the example above, the variable fileContent would contain the full content of the file.

Depending on the operating system and activation type it can be impossible to write on the file, check the Inside the Plugin Section for more details on the operating systems and situations where writting is not possible.

Configuring the Plugin¶

The configuration interface is under Window -> ImaginationOverflow -> Universal File Association -> Configuration

On some platforms, the operating system asks the player what app she wishes to use after opening a file, the Display Name allows you to configure what name will the OS show on that occasion. The Steam App Id is for Steam only games, you can read about Steam integration on its section. The plugin allows you to configure the file association globally on a per-platform basis.

Global Configuration¶

If you wish to register the same file associations for all your target platforms, you only require to configure the Global settings, the plugin will propagate all data to all platforms as you build for them.

While you setup your required extensions the plugin will automatically match them with a Mime Type or UIT, these relations between extensions and type format is required by some platforms (e.g iOS, Linux, Android).

Per Platform Configuration¶

When you wish to override any configuration for a specific platform you can do that by clicking on the specific platform checkbox. After that, you just need to fill out the File Association data or leave it empty if you do not wish to support these features for that specific platform. Note that by checking a platform none of the global configurations will be used for that specific platform.

In the example above, we've changed the iOS file extension to myextios. The remaining platforms will continue to use the global configurations.

Testing¶

After your Unity app or game is deployed to a device, you can test the integration simply by opening a file from one of the types that you registered using the Universal File Association plugin.

For integration tests you can use our Online Test Tool which allows you to create a simple text file with any extension, and download it directly to your device to be opened.

Any third party file explorer or email application could also be used to open files and test the plugin integration.

Editor¶

We included a simple interface where you can test your file association integration without deploying, to access it go to Window -> ImaginationOverflow -> Universal File Association -> Debug

When you press Debug, the FileActivated will be triggered and your callback called if the application is running in the editor.

Standalone Caveats¶

Build for MacOS¶

If you make your Mac builds on MacOS the plugin will automatically configure everything that is required in order for it to work correctly. But if you make your MacOs build on Windows you will need to do some extra steps in order to fully configure your build to receive file activations. Due to Unity limitations, you will need a Mac or a MacOs VM in order to completely use the plugin capabilities.

Building for MacOS on Windows¶

When the build is completed you will note that the build process created an extra folder named UniversalFileAssociationScripts. This folder contains all tools required to correctly finish up the plugin configuration:

Copy the UniversalFileAssociationScripts and your deliverable (you_game.app) to your Mac or VM.
Open a Terminal and navigate to the copied items location.
Run the setup.sh script:
```
./setup.sh
```

If everything goes as expected you should see something similar to the following image:

For more information on why you need to do this extra step check our Inside the Plugin Section.

Linux and Windows¶

On Windows and Linux standalone builds, the File Association is only configured when the game runs the first time, so even if the player has the game installed on his machine, if he didn't play at least one time, the File association won't activate the app/game.

Windows and Linux builds also only allow players to start your game via a File Association if the player opens a file after your game is already open the plugin won't react to this new activation.

For further details on why this happens, and how to work around it, you can check our Inside the Plugin Section.

Notes¶

If you don't own a mac you can always create a Mac VM
If you are targetting a platform that the plugin doesn't support, you will find that building to an unsupported platform will yield an error stating that the assembly ImaginationOverflow.UniversalFileAssociation.Platform.dll is not present. To fix this you will find a dummy assembly under Assets\Plugins\ImaginationOverflow\UniversalFileAssociation\libs\Dummy, configure it to be included on the unsupported platform that you are targetting and the error should be fixed.