Entities¶

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 that your entity will represent). 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.

Working with Entities¶

Creating an Entity¶

Note

You do necessarily need to create an entity on your own. The Comment, Like, and Share utility functions will automatically create any specified entities.

- (void)createEntity {
    SZEntity *entity = [SZEntity entityWithKey:@"my_key_or_url" name:@"An Entity"];
    [SZEntityUtils addEntity:entity success:^(id<SZEntity> entity) {
        NSLog(@"Created entity %@/%d", [entity key], [entity objectID]);
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];
}

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 Object Structure in the API Docs. for more detail on these aggregate values.

- (void)getEntity {
    [SZEntityUtils getEntityWithKey:@"my_key_or_url" success:^(id<SZEntity> entity) {
        NSLog(@"Retrieved entity %@/%d", [entity key], [entity objectID]);
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];
}

You can also retrieve several entities in one call:

- (void)getMultipleEntitiesById {
    NSArray *ids = [NSArray arrayWithObjects:[NSNumber numberWithInt:1], [NSNumber numberWithInt:2], [NSNumber numberWithInt:3], nil];
    [SZEntityUtils getEntitiesWithIds:ids success:^(NSArray *entities) {
        for (id<SZEntity> entity in entities) {
            NSLog(@"Retrieved entity %@/%d", [entity key], [entity objectID]);            
        }
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];
}

Or page through entities for the entire application

- (void)getAllEntitiesForApplication {
    [SZEntityUtils getEntitiesWithFirst:[NSNumber numberWithInteger:0] last:[NSNumber numberWithInteger:50] success:^(NSArray *entities) {
        for (id<SZEntity> entity in entities) {
            NSLog(@"Retrieved entity %@/%d", [entity key], [entity objectID]);            
        }
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];
}

You can select a sort order for listed entities

- (void)getPopularEntitiesForApplication {
    [SZEntityUtils getEntitiesWithSorting:SZResultSortingPopularity first:nil last:nil success:^(NSArray *entities) {
        for (id<SZEntity> entity in entities) {
            NSLog(@"Retrieved entity %@/%d", [entity key], [entity objectID]);            
        }
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];
}

Entity Stats¶

Each entity object retrieved from the server contains aggregate statistics about the number of comments,likes,views and shares:

- (void)getUserStats {
    [SZEntityUtils getEntitiesWithFirst:[NSNumber numberWithInteger:0] last:[NSNumber numberWithInteger:50] success:^(NSArray *entities) {
        for (id<SZEntity> entity in entities) {
            
            // userActionSummary contains information about how the authenticated user has acted on this entity
            NSDictionary *userActions = [entity userActionSummary];
            BOOL isLiked = [[userActions objectForKey:@"likes"] integerValue] > 0;
            NSNumber *comments = [userActions objectForKey:@"comments"];
            NSLog(@"The user has %@ comments, liked=%d, total likes=%d, total comments=%d, total shares=%d", comments, isLiked, [entity likes], [entity comments], [entity shares]);
        }
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];
}

Entity Metadata¶

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.

- (void)createEntityWithMeta {
    SZEntity *entity = [SZEntity entityWithKey:@"my_key_or_url" name:@"An Entity"];
    entity.meta = @"123";
    
    [SZEntityUtils addEntity:entity success:^(id<SZEntity> serverEntity) {
        NSLog(@"Created entity with meta %@", [serverEntity meta]);
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];

}

If you want a more complex data structure, we recommend using JSON as an object notation. To do this, you will need to use a third party library such as the excellent JSONKit

- (void)createEntityWithJSONMeta {
    SZEntity *entity = [SZEntity entityWithKey:@"my_key_or_url" name:@"An Entity"];
    
    NSDictionary *dictionary = [NSDictionary dictionaryWithObject:@"123" forKey:@"key"];
    entity.meta = [dictionary JSONString];
    
    [SZEntityUtils addEntity:entity success:^(id<SZEntity> serverEntity) {
        NSDictionary *retrievedDictionary = [[entity meta] objectFromJSONString];
        NSLog(@"Retrieved meta: %@", retrievedDictionary);
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];
    
}

Entity Activity¶

For information on retrieving a social activity stream for a given entity, see the Actions Section.

Entities Without URLs¶

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

- (void)createEntityWithCustomPageInfo {
    SZEntity *entity = [SZEntity entityWithKey:@"my_key_or_url" name:@"An Entity"];

    NSDictionary *params = [NSDictionary dictionaryWithObjectsAndKeys:
                            @"Some title for the page, if you don't want to use the entity name", @"szsd_title",
                            @"Description text on the page if there is no URL to parse", @"szsd_description",
                            @"http://the_url_to_your_thumbnail_image", @"szsd_thumb",
                            nil];
    
    NSError *error = nil;
    NSData *jsonData = [NSJSONSerialization dataWithJSONObject:params options:0 error:&error];
    NSAssert(error == nil, @"Error writing json: %@", [error localizedDescription]);
    NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
    entity.meta = jsonString;
    
    [SZEntityUtils addEntity:entity success:^(id<SZEntity> serverEntity) {
        NSLog(@"Successfully updated entity meta: %@", [serverEntity meta]);
    } failure:^(NSError *error) {
        NSLog(@"Failure: %@", [error localizedDescription]);        
    }];
}

This will display on your entity page like this: