AWS Mobile Blog

Improvements in the AWS Mobile SDK for Unity

by Mudeem Siddiqui | on | Permalink | Comments |  Share

AWS Mobile SDK for Unity has been in Developer Preview since December (see my blog post, Announcing AWS Mobile SDK for Unity Developer Preview to learn more). In February, we added support for Amazon Mobile Analytics (see Announcing Amazon Mobile Analytics in the AWS Mobile SDK for Unity).

We have been actively working on incorporating the great feedback we have received during the Developer Preview. Based on what we heard, we are introducing improvements to the AWS Mobile SDK for Unity that may require you to change your code when you incorporate the latest version of the AWS Mobile SDK for Unity. We believe these updates and the new features will make the SDK easier to use and more configurable. 

So what has changed with this new release?

1. Introducing typed response objects for service clients and simpler method forms

Today, the code to get objects from an Amazon S3 bucket is as follows:

var request = new GetObjectRequest()
{
  BucketName = bucketName,
  Key = downloadKey
};
 
S3Client.GetObjectAsync (request, (result)=>
{
GetObjectResponse response = (GetObjectResponse)result.Response;
//do something with the response ...
},null);

In this approach you need to know the type of response object that may require browsing through the code. This is not a great experience. In the next version of the SDK, the result objects are typed to a specific request and response so you no longer have to cast them yourself. In addition, the SDK supports simpler method forms that do not require you to create the request object. The SDK automatically creates the request objects based on the input parameters. E.g

S3Client.GetObjectAsync (bucketName,key, (result)=>
{
 	var response = result.Response;
 	//do something with the response ...
},null);

2. The ability to receive responses in a background thread

We are introducing the AsyncOptions.ExecuteOnMainThread property that enables you to have the response delivered to a background thread. By default the response is returned on the Main thread as the ExecuteOnMainThread is defaulted to true. This is a significant improvement over the existing behavior where the response is only delivered on the Main thread.

3. APIs for Amazon DynamoDB high-level client are now asynchronous

Having synchronous API calls for Amazon DynamoDB high-level client required you to invoke these calls in a background thread to avoid Main thread locks. We identified this as one of the potential pitfalls when using Amazon DynamoDB high-level client. From this new release onwards, we are providing only asynchronous APIs for all services.

4. Removed IdentityProvider pattern

Up until now (version <= 1.0.5), you had to use the IdentityProvider property to perform an operation on CognitoAWSCredentials E.g

var credentials = new CognitoAWSCredentials(IDENTITY_POOL_ID, RegionEndpoint.USEast1);
// to use Facebook authentication
credentials.IdentityProvider.Logins.Add ("graph.facebook.com", "facebook_token");

In the newer versions of the SDK, you can perform the same operations directly using the CognitoAWSCredentials class methods.

var credentials = new CognitoAWSCredentials(IDENTITY_POOL_ID, RegionEndpoint.USEast1);
credentials.AddLogin("graph.facebook.com", "facebook_token");

For Developer Authenticated Identities, we have added a mechanism to extend the CognitoAWSCredentials and override the RefreshIdentity() method to refresh the identity Id. You now implement Developer Authenticated Identity as follows:

public class CustomCognitoCredentials : CognitoAWSCredentials
{
    public IdentityState RefreshIdentity()
    {
       //return valid identity state object
    }
}

5. Transient caching of Amazon Cognito credentials

The new release of the AWS Mobile SDK for Unity uses player preferences for caching the identity Id. The short lived credentials are only cached in memory and are scoped at object level. While this may result in additional HTTP calls when multiple instances of credentials are created, it makes your application more secure.

6. Centralized management of service configurations using awsconfig.xml

In the earlier versions of the SDK, only Amazon Mobile Analytics supported custom configurations. We have extended this to Amazon DynamoDB, and Amazon S3. E.g now in Amazon DynamoDB you can configure the table structure using awsconfig.xml. Configurations for Amazon Mobile Analytics are also moved to awsconfig.xml. Through awsconfig.xml, you can also configure log settings. Here is an example configuration:

<aws region="us-west-2">
  <logging logTo="UnityLogger" logResponses="Always" logMetrics="true" />
  <s3 useSignatureVersion4="true" />
 
  <dynamoDB>
    <dynamoDBContext tableNamePrefix="Prod-">
 
      <tableAliases>
        <alias fromTable="FakeTable" toTable="People" />
        <alias fromTable="Persons" toTable="People" />
      </tableAliases>
 
      <mappings>
        <map type="Sample.Tests.Author, SampleDLL" targetTable="People" />
        <map type="Sample.Tests.Editor, SampleDLL" targetTable="People">
          <property name="FullName" attribute="Name" />
          <property name="EmployeeId" attribute="Id" />
          <property name="ComplexData" converter="Sample.Tests.ComplexDataConverter, SampleDLL" />
          <property name="Version" version="true" />
          <property name="Password" ignore="true" />
        </map>
      </mappings>
 
    </dynamoDBContext>
  </dynamoDB>
</aws>

7. Abstract Class replaced by Default Implementation Classes

In previous releases, the public APIs often had an abstract class and a default class with implementation. E.g

CognitoSyncManager manager = new DefaultCognitoSyncManager(IdentityPoolId, region);//for default implementation
 CognitoSyncManager manager = new CustomCognitoSyncManager()//for my custom implementation
 ...
 public class CustomCognitoSyncManager : CognitoSyncManager 
 {
  //my custom implementation for all the api's
 }

In this case the CognitoSyncManager is the abstract class and DefaultCognitoSyncManager provides the default implementation. While this provides a mechanism to implement custom logic, developers told us that, in most cases, they only wanted to overwrite a subset of the methods rather than all the default class methods. In light of this, we are eliminating the abstract class approach and instead, providing a single class with a default implementation. This means the above example will now look like this:

CognitoSyncManager manager = new CognitoSyncManager(IdentityPoolId, region);//for default implementation
 CognitoSyncManager manager = new CustomCognitoSyncManager()//for my custom implementation
 ...
 public class CustomCognitoSyncManager : CognitoSyncManager 
 {
  //my custom implementation for only custom api's
 }

8. Updated Namespaces and Class Names

With the new version of the SDK, the namespaces and class names are updated for simplicity and to improve clarity. The new standard is as follows:

Amazon.<ServiceName> //for low level api's
Amazon.<ServiceName>.<HighLevelFunctionality> //for high level functionality

For example, this means that Amazon Mobile Analytics is now defined as:

Amazon.MobileAnalytics //for low level api's
Amazon.MobileAnalytcs.MobileAnalyticsManager // for high level functionality

In addition the word "Amazon" is stripped from names of the classes as it is already a part of the namespace. E.g for a custom event in Amazon Mobile Analytics, AmazonMobileAnalyticsEvent is replaced with just CustomEvent. The code to record custom event looks like:

CustomEvent customEvent = new CustomEvent("level_complete");  
 
customEvent.AddAttribute("LevelName","Level1");
customEvent.AddAttribute("Successful","True");
customEvent.AddMetric("Score",12345);
customEvent.AddMetric("TimeInLevel",64);   
analyticsManager.RecordEvent(customEvent);

9. New Features

Last but not the least, we have added a number of new features for Amazon S3 and Amazon DynamoDB. For Amazon S3, the next SDK update adds support for DeleteObject(), GetACL(), ListVersions(), GetBucketPolicy(), GetCORSConfiguration() and more. Similarly for Amazon DynamoDB we have added Document Model Support with JSON, DynamoDB Expressions, Scan API for Secondary Indexes, and support for creating, updating and deleting Global Secondary Indexes.

If you have any questions or suggestions, you can provide feedback here