Activities

"In its simplest form, an activity consists of an actor, a verb, and an object. It tells the story of a person performing an action on or with an object."

Activity Streams Specification 1.0

Adding an activity in its simplest form means passing an object with the following basic properties:

• Actor

• Verb

• Object

• Recommended:

  • Foreign Id

  • Time

Here's an example:

“Erik is pinning Hawaii to his Places to Visit board.”

Let's break the example down:

• Actor: "Eric" (User:1)

• Verb: "pin"

• Object: "Hawaii" (Place:42)

• Foreign Id: "Eric's board activity" (Activity:1)

• Time: 2017-07-01T20:30:45.123

Now, let's show you how to add an activity to a feed using your Stream API client:

Listed below are the mandatory and recommended fields when adding Activities.

In the above example, the  course,  location,  participants  and  started_at  fields will be stored with the Activity and included whenever the Activity is retrieved.

For performance reasons, activities are limited in size (4KB) and must not contain blob/binary data (e.g. base64 encoded images). Use references and identifiers to facilitate Activity enrichment by your backend or client.

Foreign IDs

The example above also specified a foreign_id.

The foreign id is a unique identifier for the activity that can be stored and used within the app. Making use of the the foreign id field is highly recommended as it is needed in order to update Activities.

When an activity is successfully added, the Stream API includes activity id in the serialized JSON response, like so:

The example below shows how to retrieve the Activities in a feed:

Activity reads returns at most 100 Activities. Requests with a limit greater than 100 are automatically capped.

The recommended way to paginate feeds is with offset and limit parameters. Such approach makes for simpler code and it works for all types of feeds.

When a feed is successfully retrieved, the Stream API returns the following payload:

The format for results array depends on the type of feed associated with the notification. When a Flat Feed is retrieved, the array contains Activities. Whereas when an Aggregated or Notification Feed is retrieved, the array contains Activity Groups.

The 'next' property in the response contains a URL that may be used to retrieve the next page of activities within the feed.

There are two ways to remove an activity:

• Activity Id - found in the serialized response from server

• Foreign Id - optionally specified when adding an activity

Have a look at the section on Using Foreign IDs.

Activities that have both foreign_id and time defined can be updated via the APIs. Changes to activities immediately show up on every feed.

This API method works particularly well in combination with the ranked feeds. You can, for instance, issue an update if an activity is promoted or not and use the ranked feeds to show it higher in the feed. Similarly, you could update the like and comment counts and use a ranking method based on popularity to sort the activities.

It is possible to update only a part of an activity with the partial update request. You can think of it as a quick "patching operation".

The activity to update can be selected by its ID or Foreign ID and Time combination.

A set and an unset params can be provided to add, modify, or remove attributes to/from the target activity. The set and unset params can be used separately or combined together (see below).

The set object contains the insertion updates for the target fields, where the keys are the activity fields to update and the values are the new ones to assign. If the target field does not exist, it's created with the given content. If the target field exists, its content is replaced.

It is possible to quickly reference nested elements using the dotted notation (father.child. ...), but in this case the whole hierarchy is required to exist and to be valid.

For example, if the target activity looks like the following:

It is possible to update the product's EUR price with the key "product.price.eur", or even create a new field with the key "product.price.gbp", but it's not possible to reference a non-existing hierarchy like "product.colors.blue".

The unset field contains a list of key strings that will be removed from the activity's payload. They must exist, and, if referenced with the dotted notation, their hierarchy must be valid.

The set and unset fields can be combined in the same request, but they must not be conflicting with each other (they must not have operations referencing the same keys or hierarchies).

The following example shows a valid combination of set and unset operations which will update the above example activity:

It is also possible to partially update activities in batches. The same individual activity restrictions are applied, and there's a limit of 100 activities per batch.

Activities in each batch can be identified either by their ID or by the ForeignID and Time combination:

Stream handles uniqueness based on the foreign_id and time fields. If you want to be able to update your activities you need to specify both of these fields.

Uniqueness is enforced on the combination of time and foreign_id. See the example below for an overview:

By default, activity upsert by this uniqueness guarantee is enabled and it can be disabled per application in the server side by contacting to support. Additionally, it's also disabled if a request is using a client side authentication or has disable_activity_upsert query parameter.