Set Up the AWS Mobile SDK for Unity
To get started with the AWS Mobile SDK for Unity, you can set up the SDK and start building a new project, or you can integrate the SDK with an existing project. You can also clone and run the samples to get a sense of how the SDK works.
Before you can use the AWS Mobile SDK for Unity, you will need the following:
- An AWS Account
- Unity version 4.x or 5.x (Unity 4.6.4p4 or Unity 5.0.1p3 is required if you want to write applications that run on iOS 64-bit)
After completing the prerequisites, you will need to do the following to get started:
- Download the AWS Mobile SDK for Unity.
- Configure the AWS Mobile SDK for Unity.
- Obtain AWS credentials using Amazon Cognito.
First, download the AWS Mobile SDK for Unity. Each package in the SDK is required to consume the corresponding AWS service based on the package's name. For example, the aws-unity-sdk-dynamodb-188.8.131.52.unitypackage package is used to call the AWS DynamoDB service. You can import all of the packages or just the ones you intend to use.
- Open the Unity editor and create a new empty project, use the default settings.
- Select Assets > Import Package > Custom Package.
- In the Import package dialog, navigate to and select the .unitypackage files you want to use.
- In the Importing package dialog, ensure all items are selected and click Import.
When working with the AWS Mobile SDK for Unity, you can get started by including the following line
of code in the
Awake method of your mono behavior class:
Create your scene by choosing New Scene from the File menu.
The AWS SDK for Unity contains client classes for each AWS service it supports. These clients are configured using a file named awsconfig.xml. The following section describes the most commonly used settings in the awsconfig.xml file. For more information about these settings, see the Unity SDK API Reference.
To configure the default region for all service clients:
<aws region="us-west-2" />
This sets the default region for all the service clients in the Unity SDK. This setting can be overridden by explicitly specifying the region at the time of creating an instance of the service client, like so:
IAmazonS3 s3Client = new AmazonS3Client(<credentials>,RegionEndpoint.USEast1);
Logging settings are specified as follows:
<logging logTo="UnityLogger" logResponses="Always" logMetrics="true" logMetricsFormat="JSON" />
This setting is used to configure logging in Unity. When you log to
framework internally prints the output to the Debug Logs. If you want to log HTTP responses, set the
logResponses flag - the values can be Always, Never, or OnError. You can also log performance
metrics for HTTP requests using the logMetrics property, the log format can be specified using
LogMetricsFormat property, valid values are JSON or standard.
The following example shows the most commonly used settings in the awsconfig.xml file. For more information about specific service settings, see the service section below:
<?xml version="1.0" encoding="utf-8"?> <aws region="us-west-2" <logging logTo="UnityLogger" logResponses="Always" logMetrics="true" logMetricsFormat="JSON" /> />
The SDK uses reflection for platform-specific components. If you are using the IL2CPP scripting
strip bytecode is always enabled on iOS, so you need to have a
file in your assembly root with the following entries:
<linker> <!-- if you are using AWSConfigs.HttpClient.UnityWebRequest option--> <assembly fullname="UnityEngine"> <type fullname="UnityEngine.Experimental.Networking.UnityWebRequest" preserve="all" /> <type fullname="UnityEngine.Experimental.Networking.UploadHandlerRaw" preserve="all" /> <type fullname="UnityEngine.Experimental.Networking.UploadHandler" preserve="all" /> <type fullname="UnityEngine.Experimental.Networking.DownloadHandler" preserve="all" /> <type fullname="UnityEngine.Experimental.Networking.DownloadHandlerBuffer" preserve="all" /> </assembly> <assembly fullname="mscorlib"> <namespace fullname="System.Security.Cryptography" preserve="all"/> </assembly> <assembly fullname="System"> <namespace fullname="System.Security.Cryptography" preserve="all"/> </assembly> <assembly fullname="AWSSDK.Core" preserve="all"/> <assembly fullname="AWSSDK.CognitoIdentity" preserve="all"/> <assembly fullname="AWSSDK.SecurityToken" preserve="all"/> add more services that you need here... </linker>
To use AWS services in your mobile application, you must obtain the Identity Pool ID using Amazon Cognito Identity. Using Amazon Cognito to obtain the Identity Pool ID allows your app to access AWS services without having to embed your private credentials in your application. This also allows you to set permissions to control which AWS services your users have access to.
To get started with Amazon Cognito, you must create an identity pool. An identity pool is a store of user identity data specific to your account. Every identity pool has configurable IAM roles that allow you to specify which AWS services your application's users can access. Typically, a developer will use one identity pool per application. For more information on identity pools, see the Amazon Cognito Developer Guide.
To create an identity pool for your application:
- Log in to the Amazon Cognito Console and click Create new identity pool.
- Enter a name for your Identity Pool and check the checkbox to enable access to unauthenticated identities. Click Create Pool to create your identity pool.
- Click Allow to create the two default roles associated with your identity pool--one for unauthenticated users and one for authenticated users. These default roles provide your identity pool access to Cognito Sync and Mobile Analytics.
The next page displays code that creates a credentials provider so you can easily integrate Cognito Identity with your Unity application. You pass the credentials provider object to the constructor of the AWS client you are using. The code looks like this:
CognitoAWSCredentials credentials = new CognitoAWSCredentials ( "IDENTITY_POOL_ID", // Identity Pool ID RegionEndpoint.USEast1 // Region );
- Get Started: Read Getting Started with the AWS Mobile SDK for Unity to get a more detailed overview of the services included in the SDK.
- Run the demos: View our sample Unity applications that demonstrate common use cases. To run the sample apps, set up the SDK for Unity as described above, and then follow the instructions contained in the README files of the individual samples.
- Read the API Reference: View the API Reference for the AWS Mobile SDK for Unity.
- Ask questions: Post questions on the AWS Mobile SDK Forums or open an issue on Github.