Socialize Entities¶

An Entity is the term Socialize uses to describe any item of content within your app. This could be anything from a News Article to a Hamburger and simply provides a reference point from which your users can perform social actions such as liking, commenting and sharing.

For example, imagine your app is a photography app where users can share photos they take with their device. In this scenario each photo would be an entity and users can then perform social actions on this entity.

Note

It is recommended that where possible an HTTP URL be used for your entity key

Entities in Socialize MUST be associated with a unique key. It is recommended that where possible an HTTP URL be used (i.e. one that corresponds to an active web page). If your entities do not have web addressable URLs Socialize can automatically generate an Entity Page for you. Refer to the Entities Without URLs section on this page for more information.

Auto-Creation of Entities¶

In most cases Socialize will automatically create an entity for you based on the information you provide to a particular call in the SDK.

For example, if you are using the Socialize Action Bar the entity that you pass to the Action Bar will be automatically created for you if it does not already exist.

Note

You should always specify a name when creating an entity, however if you have previously created the entity with a name and do not want to specify the name every time you can provide a “null” argument for the name. This will instruct Socialize to ignore the name attribute and the name of the entity will NOT be updated.

// Your entity key. 
String entityKey = "http://www.getsocialize.com";

// Create an entity object including a name
// The Entity object is Serializable, so you could also store the whole object in the Intent
Entity entity = Entity.newInstance(entityKey, "Socialize");

// The entity will be automatically created in the Socialize back end when this call completes.
View actionBarWrapped = ActionBarUtils.showActionBar(this, R.layout.actionbar, entity);

Manual Creation of Entities¶

If you want complete control over the lifecycle of an entity you can also create or edit any entity in the system manually

To create an entity, simply call the saveEntity method:

Entity entity = Entity.newInstance("key", "name");

// The "this" argument refers to the current Activity
EntityUtils.saveEntity(this, entity, new EntityAddListener() {
	
	@Override
	public void onError(SocializeException error) {
		// Handle error
	}
	
	@Override
	public void onCreate(Entity result) {
		// Handle success
	}
});

Retrieving Entity Data¶

An existing entity can be retrieved via the getEntity method. Entities obtained in this way will also provide aggregate data on comments, likes, shares and views. Refer to the Entity Stats (Global) section for more detail on these aggregate values.

// The "this" argument refers to the current Activity	
EntityUtils.getEntity(this, "key", new EntityGetListener() {
	
	@Override
	public void onGet(Entity result) {
		// Handle success
	}
	
	@Override
	public void onError(SocializeException error) {
		if(isNotFoundError(error)) {
			// No entity found
		}
		else {
			// Handle error
		}
	}
});

You can also retrieve several entities in one call:

// The "this" argument refers to the current Activity
EntityUtils.getEntities(this, new EntityListListener() {

	@Override
	public void onList(ListResult<Entity> result) {
		
		int count = result.getTotalCount();
		List<Entity> items = result.getItems();
		
		// Handle success
	}
	
	@Override
	public void onError(SocializeException error) {
		// Handle error
	}
}, "key0", "key1");

Retrieving Popular Entities¶

You can retrieve a list of entities ordered by popularity (activity) by passing a SortOrder paramter to the getEntities method

// Retrieve the top 10 most popular entities
	
// The "this" argument refers to the current Activity
EntityUtils.getEntities(this, 0, 10, SortOrder.TOTAL_ACTIVITY, new EntityListListener() {

	@Override
	public void onList(ListResult<Entity> result) {
		
		int count = result.getTotalCount();
		List<Entity> items = result.getItems();
		
		// Handle success
	}
	
	@Override
	public void onError(SocializeException error) {
		// Handle error
	}
});

Entity Meta Data¶

Entities stored in Socialize can optionally include meta data. This is for any additional information you want to store about the entity.

Meta data is stored with the entity and returned then the entity is requested.

Entity entity = Entity.newInstance("key", "name");
entity.setMetaData("meta data");

// The "this" argument refers to the current Activity
EntityUtils.saveEntity(this, entity, new EntityAddListener() {
	
	@Override
	public void onError(SocializeException error) {
		// Handle error
	}
	
	@Override
	public void onCreate(Entity result) {
		// Entity was created
	}
});

// Later, when you retrieve the entity...
	
EntityUtils.getEntity(this, "key", new EntityGetListener() {
	
	@Override
	public void onGet(Entity result) {
		// Get the meta data
		String metaData = result.getMetaData();
	}
	
	@Override
	public void onError(SocializeException error) {
		if(isNotFoundError(error)) {
			// No entity found
		}
		else {
			// Handle error
		}
	}
});

If you want a more complex data structure, we recommend using JSON as an object notation

	
Entity entity = Entity.newInstance("key", "name");

// Store a custom dictionary as a JSON object
JSONObject metaData = new JSONObject();
metaData.put("some_key", "some_value");

entity.setMetaData(metaData.toString());

// The "this" argument refers to the current Activity
EntityUtils.saveEntity(this, entity, new EntityAddListener() {
	
	@Override
	public void onError(SocializeException error) {
		// Handle error
	}
	
	@Override
	public void onCreate(Entity result) {
		// Entity was created
	}
});


// Later, when you retrieve the entity...
	
EntityUtils.getEntity(this, "key", new EntityGetListener() {
	
	@Override
	public void onGet(Entity result) {
		// Get the meta data
		String metaData = result.getMetaData();
		
		try {
			JSONObject json = new JSONObject(metaData);
			String myValue = json.getString("some_key");
		}
		catch (JSONException e) {
			// Handle error
		}
	}
	
	@Override
	public void onError(SocializeException error) {
		if(isNotFoundError(error)) {
			// No entity found
		}
		else {
			// Handle error
		}
	}
});

Entities Without URLs¶

Please Note

Customizing the entity page is optional and only required if your entity key does not correspond to a valid URL. If your entities already exist on the web then we recommend you defer to the standard behaviour for the entity page which is to dynamically parse the contents of your entity URL.

All entities in Socialize will be given an automatically generated entity page which forms part of the Socialize SmartDownload process.

This default entity page can be completely customized to suit the look and feel of your app as well as being able to display specific information taken from your entity meta data.

Note

If your entity key uses an HTTP URL the contents of your entity page will be automatically parsed from that URL by default

To customize the content displayed on your entity pages simply add a JSON structure to your entity meta data that includes the following szsd_ prefixed attributes:

{
    "szsd_thumb":"http://the_url_to_your_thumbnail_image", 
    "szsd_title": "Some title for the page, if you don't want to use the entity name", 
    "szsd_description": "Description text on the page if there is no URL to parse"
}

In code this would look something like this

	
Entity entity = Entity.newInstance("key", "name");

// Store a custom dictionary as a JSON object
JSONObject metaData = new JSONObject();

metaData.put("szsd_title", "Some title for the page, if you don't want to use the entity name");
metaData.put("szsd_description", "Description text on the page if there is no URL to parse");

//Optionally add a thumbnail URL to be rendered on the entity page
metaData.put("szsd_thumb", "http://the_url_to_your_thumbnail_image");

entity.setMetaData(metaData.toString());

// The "this" argument refers to the current Activity
EntityUtils.saveEntity(this, entity, new EntityAddListener() {
	
	@Override
	public void onError(SocializeException error) {
		// Handle error
	}
	
	@Override
	public void onCreate(Entity result) {
		// Entity was created
	}
});

This will display on your entity page like this: