Usage

Setup

To correctly configure the extension you will need to inform it about your group and a salt value to use for encryption.

  • The salt value is only applicable to Android however the group is used on both.
  • The salt can be any string you require and is used to setup the file encryption algorithm.

For the group, you should use the identifier of your AppGroup setup in the iOS member center. (With Unity this is the same value as you entered into the AppGroupDefaultsConfig file as the groupIdentifier).

This is used to identify the correct group to use on iOS and similarly on Android it's used as the name of the file containing the preferences.

AIR
AppGroupDefaults.service.setup(
"12345678",
"group.com.distriqt.test",
AppGroupDefaults.TYPE_CONTENTPROVIDER
);
Unity
AppGroupDefaults.Instance.Setup(
"12345678",
"group.com.distriqt.test",
AppGroupDefaults.TYPE_CONTENTPROVIDER
);

The setup call can take a short amount of time to initialise the encryption algorithms so you should wait for the initialised event before attempting to read or write values.

With AIR you listen for the AppGroupDefaultsEvent.INITIALISED event and with Unity add a listener to the OnInitialised event.

AIR
AppGroupDefaults.service.addEventListener( AppGroupDefaultsEvent.INITIALISED, initialisedHandler );
AppGroupDefaults.service.setup(
"12345678",
"group.com.distriqt.test",
AppGroupDefaults.TYPE_FILE
);
function initialisedHandler( event:AppGroupDefaultsEvent ):void
{
// Access data here
}
Unity
AppGroupDefaults.Instance.OnInitialised += Instance_OnInitialised;
AppGroupDefaults.Instance.Setup(
"12345678", // salt
"group.com.distriqt.test", // app group identifier
AppGroupDefaults.TYPE_CONTENTPROVIDER // Android type
);
void Instance_OnInitialised(distriqt.plugins.appgroupdefaults.events.AppGroupDefaultsEvent e)
{
// Access data here
}

Get Values

Retrieving a value is as simple as calling getValue() with the key of interest.

AIR
trace( "value = " + AppGroupDefaults.service.getValue( "some_key" ) );
Unity
Debug.Log("value = " + AppGroupDefaults.Instance.GetValue( "some_key" ));

This will return null if the key hasn't been set before or if you haven't called setup beforehand.

Set Values

Setting a value is likewise as simple, calling the setValue function.

AIR
var success:Boolean = AppGroupDefaults.service.setValue( "some_key", "some_value" );
Unity
bool success = AppGroupDefaults.Instance.SetValue("some_key", "some_value");

This will return true if the value was set correctly and false if there was an issue, most likely that the setup function hasn't been called, or if the isSupported flag is false.

Listing Keys

You can use the getKeys function to retrieve an Array of all the current keys set in the defaults.

This allows you to list all settings currently stored in the defaults.

AIR
var keys:Array = AppGroupDefaults.service.getKeys();
for each (var key:String in keys)
{
var value:String = AppGroupDefaults.service.getValue( key );
trace( key + " = " + value );
}
Unity
string[] keys = AppGroupDefaults.Instance.GetKeys();
foreach (string key in keys)
{
string value = AppGroupDefaults.Instance.GetValue(key);
Debug.Log(key + " = " + value);
}

Removing a Value

If you wish to clear a value and remove it from the defaults, simply call the remove function with the key of interest.

AIR
AppGroupDefaults.service.remove( "some_key" );
Unity
AppGroupDefaults.Instance.Remove("some_key");

Removing All Values

If you wish to remove all values from the defaults, simply call the removeAll function:

AIR
AppGroupDefaults.service.removeAll();
Unity
AppGroupDefaults.Instance.RemoveAll();

AIR Example

The following example shows the core concepts, i.e. the setup process, listening to the AppGroupDefaultsEvent.INITIALISED event, and getting and setting values.

AIR
if (AppGroupDefaults.isSupported)
{
AppGroupDefaults.service.addEventListener( AppGroupDefaultsEvent.INITIALISED, initialisedHandler );
AppGroupDefaults.service.setup(
"12345678",
"group.com.distriqt.test",
AppGroupDefaults.TYPE_FILE
);
}
function initialisedHandler( event:AppGroupDefaultsEvent ):void
{
var someValue:String = AppGroupDefaults.service.getValue( "some_key" );
AppGroupDefaults.service.setValue("anotherKey", "Sample text from AIR!");
}

Unity Example

The following example shows the core concepts, i.e. the setup process, listening to the OnInitialised event, and getting and setting values.

Unity
if (AppGroupDefaults.isSupported)
{
AppGroupDefaults.Instance.OnInitialised += Instance_OnInitialised;
AppGroupDefaults.Instance.Setup(
"12345678", // salt
"group.com.distriqt.test", // app group identifier
AppGroupDefaults.TYPE_CONTENTPROVIDER // Android type
);
}
private void Instance_OnInitialised(AppGroupDefaultsEvent e)
{
Debug.Log("OnInitialised");
string someValue = AppGroupDefaults.Instance.GetValue("someKey");
AppGroupDefaults.Instance.SetValue("anotherKey", "Sample text from Unity!");
}