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 Activities: Basic

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:

// Instantiate a feed object
var userFeed1 = client.Feed("user", "1");

// Add an activity to the feed, where actor, object and target are references to objects (`Eric`, `Hawaii`, `Places to Visit`)

var activity = new Activity("User:1", "pin", "Place:42");
await userFeed1.AddActivityAsync(activity);

# Instantiate a feed object
user_feed_1 = client.feed('user', '1')
# Add an activity to the feed, where actor, object and target are references to objects (`Eric`, `Hawaii`, `Places to Visit`)
activity_data = {:actor => "User:1", :verb => "pin", :object => "Place:42"}
activity_response = user_feed_1.add_activity(activity_data)

# Instantiate a feed object
user_feed_1 = client.feed('user', '1')

# Add an activity to the feed, where actor, object and target are references to objects (`Eric`, `Hawaii`, `Places to Visit`)
activity_data = {"actor": "User:1", "verb": "pin", "object": "Place:42"}
activity_response = user_feed_1.add_activity(activity_data)

// Instantiate a feed object
FlatFeed userFeed = client.flatFeed("user", "1");

// Add an activity to the feed, where actor, object and target 
// are references to objects (`Eric`, `Hawaii`, `Places to Visit`)
Activity activity = Activity.builder()
    .actor("User:1")
    .verb("pin")
    .object("Place:42")
    .target("Board:1")
    .build();
userFeed.addActivity(activity).get();

// Instantiate a feed object
	userFeed, err := client.FlatFeed("user", "1")
	if err != nil {
		panic(err)
	}

	// Add an activity to the feed, where actor, object and verb are references to objects (`Eric`, `Hawaii`, `Places to Visit`)
	activity := stream.Activity{
		Actor: "User:1",
		Verb:  "pin",
		Object: "Place:42",
	}
	_, err := userFeed.AddActivity(context.TODO(), activity)
	if err != nil {
		panic(err)
	}

// Instantiate a feed object
$userFeed1 = $client->feed('user', '1');

// Add an activity to the feed, where actor, object and target are references to objects (`Eric`, `Hawaii`, `Places to Visit`)
$data = [
  "actor"=>"User:1",
  "verb"=>"pin",
  "object"=>"Place:42"
];

$userFeed1->addActivity($data);

let userFeed = Client.shared.flatFeed(feedSlug: "user")
let activity = Activity(actor: User.current!, verb: "pin", object: "Place:42")

userFeed?.add(activity) { result in
  if let activity = try? result.get() {
    // Added activity
    print(activity.id)
  }
}

// Server-side: Instantiate a feed using feed group 'user' and user id '1'
const user1 = client.feed('user', '1');

// Client-side: Instantiate a feed for feed group 'user', user id '1' 
// and a security token generated server side
const user1 = client.feed('user', '1', token);

// Create an activity object
const activity = { actor: 'User:1', verb: 'pin', object: 'Place:42' };

// Add an activity to the feed
await user1.addActivity(activity);

// Instantiate a feed using feed group 'user' and user id '1'
var user1 = client.flatFeed('user', '1');

// Create an activity object
const activity = Activity(actor: 'User:1', verb: 'pin', object: 'Place:42');

// Add an activity to the feed
await user1.addActivity(activity);

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

Fields

Custom Fields

// Create a bit more complex activity
var activity = new Activity("User:1", "run", "Exercise:42")
{
	ForeignId = "run:1"
};
var course = new Dictionary<string, object>();
course["name"] = "Shevlin Park";
course["distance"] = 10;

var participants = new[] { "Thierry", "Tommaso" };

var location = new Dictionary<string, object>();
location.Add("type", "point");
location.Add("coordinates", new[] {37.769722F, -122.476944F});

activity.SetData("location", location);
activity.SetData("course", course);
activity.SetData("participants", participants);

// Server-side: Instantiate a feed using feed class 'user' and user id '1'
const user1 = client.feed('user', '1');

// Client-side: Instantiate a feed for feed group 'user', user id '1' 
// and a security token generated server side
const user1 = client.feed('user', '1', userToken);

// Create a bit more complex activity
const activity = {
  'actor': 'User:1', 
  'verb': 'run', 
  'object': 'Exercise:42',
  'course': { 'name': 'Golden Gate park', 'distance': 10 },
  'participants': ['Thierry', 'Tommaso'],
  'started_at': new Date(),
  'foreign_id': 'run:1',
  'location': { 'type': 'point', 'coordinates': [37.769722,-122.476944] }
};

await user1.addActivity(activity);

# Create a bit more complex activity
activity_data = {:actor => 'User:1', :verb => 'run', :object => 'Exercise:42',
  :course => {:name => 'Golden Gate park', :distance => 10},
  :participants => ['Thierry', 'Tommaso'],
  :started_at => DateTime.now(),
  :foreign_id => 'run:1',
  :location => {:type => 'point', :coordinates => [37.769722,-122.476944] }
}
activity_response = user_feed_1.add_activity(activity_data)

import datetime

# Create a bit more complex activity
activity_data = {'actor': 'User:1', 'verb': 'run', 'object': 'Exercise:42',
  'course': {'name': 'Golden Gate park', 'distance': 10},
  'participants': ['Thierry', 'Tommaso'],
  'started_at': datetime.datetime.utcnow(),
  'foreign_id': 'run:1',
  'location': {'type': 'point', 'coordinates': [37.769722,-122.476944] }
}
user_feed_1.add_activity(activity_data)

// Create a bit more complex activity
Activity activity = Activity.builder()
    .actor("User:1")
    .verb("run")
    .object("Exercise:42")
    .foreignID("run:1")
    .extra(new ImmutableMap.Builder<String, Object>()
        .put("course", new ImmutableMap.Builder<String, Object>()
            .put("name", "Golden Gate park")
            .put("distance", 10)
            .build())
        .put("participants", new String[]{
            "Thierry",
            "Tommaso",
        })
        .put("started_at", LocalDateTime.now())
        .put("location", new ImmutableMap.Builder<String, Object>()
            .put("type", "point")
            .put("coordinates", new double[]{37.769722, -122.476944})
            .build())
        .build())
    .build();
userFeed.addActivity(activity).join();

// Create a bit more complex activity
	activity := stream.Activity{
		Actor:   "User:1",
		Verb:   "run",
		Object:  "Exercise:42",
		ForeignID: "run:1",
		Extra: map[string]any{
			"course": map[string]any{
				"name":   "Golden Gate park",
				"distance": 10,
			},
			"participants": []string{
				"Thierry",
				"Tommaso",
			},
			"started_at": time.Now(),
		},
	}
	_, err := userFeed.AddActivity(context.TODO(), activity)
	if err != nil {
		panic(err)
	}

// Create a bit more complex activity
$now = new DateTime('now');

$data = [
  'actor' => 'User:1',
  'verb' => 'run',
  'object' => 1,
  'course' => ['name'=> 'Golden Gate park', 'distance'=> 10],
  'participants' => ['Thierry', 'Tommaso'],
  'started_at' => $now,
  'foreign_id' => 'run:1',
  'location' => [
    'type'=> 'point',
    'coordinates'=> [
      37.769722, -122.476944,
    ],
  ],
];

$userFeed1->addActivity($data);

// Create a custom Activity class.
final class ExerciseActivity: EnrichedActivity<User, String, DefaultReaction> {
  private enum CodingKeys: String, CodingKey {
    case course
    case participants
    case startDate = "started_at"
  }
  
  var course: Course
  var participants: [String] = []
  var startDate: Date = Date()
  
  init(verb: Verb, 
     object: String, 
     course: Course,
     participants: [String],
     startDate: Date = Date()) {
    super.init(actor: User.current!, verb: verb, object: object)
    self.course = course
    self.participants = participants
    self.startDate = startDate
  }
  
  required init(from decoder: Decoder) throws {
    let container = try decoder.container(keyedBy: CodingKeys.self)
    course = try container.decode(Course.self, forKey: .course)
    participants = try container.decode([String].self, forKey: .participants)
    startDate = try container.decode(Date.self, forKey: .startDate)
    try super.init(from: decoder)
  }
  
  override public func encode(to encoder: Encoder) throws {
    var container = encoder.container(keyedBy: CodingKeys.self)
    try container.encode(course, forKey: .course)
    try container.encode(participants, forKey: .participants)
    try container.encode(startDate, forKey: .startDate)
    try super.encode(to: encoder)
  }
}

struct Course: Codable {
  let name: String
  let distance: Float
}

let exerciseActivity = ExerciseActivity(verb: "run", 
                    object: "Exercise:42", 
                    course: Course(name: "Golden Gate Park", distance: 10), 
                    participants: ["Thierry", "Tommaso"])

// Add the exercise activity to the user feed. 
userFeed?.add(exerciseActivity) { result in
  print(result)
}

// Get a list of exercise activities.
userFeed?.get(typeOf: ExerciseActivity.self) { result in
  print(result)
}

// Instantiate a feed for feed group 'user', user id '1'
// and a security token generated server side
final user1 = client.flatFeed('user', '1');

// Create a bit more complex activity
final activity =
  Activity(actor: 'User:1', verb: 'run', object: 'Exercise:42', extraData: {
  'course': const {'name': 'Golden Gate park', 'distance': 10},
  'participants': const ['Thierry', 'Tommaso'],
  'started_at': DateTime.now().toIso8601String(),
  'foreign_id': 'run:1',
  'location': const {
   'type': 'point',
   'coordinates': [37.769722, -122.476944]
  }
});

await user1.addActivity(activity);

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 (10KB) 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.

Add Activity Response Data

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

{ 
  id:"ef696c12-69ab-11e4-8080-80003644b625",
  actor:"User:1",
  course:{ 
   distance:10,
   name:"Golden Gate Park"
  },
  object:"Exercise:42",
  participants:[ 
   "Thierry",
   "Tommaso"
  ],
  started_at:"2014-11-11T15:06:16+01:00",
  target:null,
  time:"2014-11-11T14:06:30.494",
  verb:"run"
}

Retrieving Activities

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

// Get activities from 5 to 10
var result = await userFeed1.GetActivitiesAsync(5, 5);

# Get the 5 activities added after lastActivity 
var result = await userFeed1.GetActivitiesAsync(0, 5, FeedFilter.Where().IdLessThan(lastActivity.id));

// Get activities sorted by rank (Ranked Feeds Enabled):
var flatActivities = await userFeed1.GetFlatActivitiesAsync(GetOptions.Default.WithLimit(5).WithRanking("popularity"));

// Get activities from 5 to 10

user1.get({ limit:5, offset:5 })
 .then(activitiesSuccess)
 .catch(activitiesError);

// Get the 5 activities added after lastActivity 

user1.get({ limit:5, id_lt: lastActivity.id })
 .then(activitiesSuccess)
 .catch(activitiesError);

// Get the 5 activities added before lastActivity 

user1.get({ limit:5, id_gt: lastActivity.id })
 .then(activitiesSuccess)
 .catch(activitiesError);

// Get activities sorted by rank (Ranked Feeds Enabled)

user1.get({ limit:20, ranking:'popularity'})
 .then(activitiesSuccess)
 .catch(activitiesError);

// Get the 5 activities and enrich them with reactions and collections

user1.get({ 
 limit:20, enrich:true,
 reactions: {own: true, counts: true, recent: true},
})
 .then(activitiesSuccess)
 .catch(activitiesError);

function activitiesSuccess(successData) {
 console.log(successData);
}

function activitiesError(errorData) {
 console.log(errorData);
}

# Get activities from 5 to 10
result = user_feed_1.get(:limit=>5, :offset=>5)

# Get the 5 activities added after last_activity 
result = user_feed_1.get(:limit=>5, :id_lt=>last_activity.id)

# Get the 5 activities added before last_activity 
result = user_feed_1.get(:limit=>5, :id_gt=>last_activity.id)

# Get activities sorted by rank (Ranked Feeds Enabled):
result = user_feed_1.get(:limit=>5, :ranking=>'popularity')

# Get activities from 5 to 10
result = user_feed_1.get(limit=5, offset=5)

# Get the 5 activities added after last_activity 
result = user_feed_1.get(limit=5, id_lt=last_activity.id)

# Get the 5 activities added before last_activity 
result = user_feed_1.get(limit=5, id_gt=last_activity.id)

# Get activities sorted by rank (Ranked Feeds Enabled):
result = user_feed_1.get(limit=5, ranking="popularity")

# Get first 5 activities and enrich them with reactions and collections
result = user_feed_1.get(
  limit=5, enrich=True, reactions={"counts": True, "recent": True},response = userFeed.feed.getActivities(
        new Limit(69),
        new Offset(13),
        DefaultOptions.DEFAULT_FILTER,
        "rank",
        new RankingVars(mp)
    );
)

// Get 3rd page with 20 activities
response = userFeed.feed.getActivities(new Limit(20), new Offset(40));

 // Get 5 activities with id less than the given UUID (Faster - Recommended!)
response = userFeed.getActivities(new Filter().idLessThan("e561de8f-00f1-11e4-b400-0cc47a024be0").limit(5)).join();

// Get activities from 5 to 10 (Pagination-based - Slower)
response = userFeed.getActivities(new Pagination().offset(0).limit(5)).join();

// Get activities sorted by rank (Ranked Feeds Enabled):
response = userFeed.getActivities(new Pagination().limit(5), "popularity").join();

// Get activities and enrich them with reactions and collections
response = userFeed.getEnrichedActivities(new EnrichmentFlags().withOwnReactions().withRecentReactions().withReactionCounts()).join();

// Get activities f
 
 
 rom 5 to 10
	resp, err := userFeed.GetActivities(
		context.TODO(),
		stream.WithActivitiesLimit(5),
		stream.WithActivitiesOffset(5),
	)
	if err != nil {
		panic(err)
	}

	// Get the 5 activities added after lastActivity
	resp, err = userFeed.GetActivities(
		context.TODO(),
		stream.WithActivitiesLimit(5),
		stream.WithActivitiesIDLT(lastActivity.ID),
	)
	if err != nil {
		panic(err)
	}

	// Get activities sorted by rank (Ranked Feeds Enabled):
	resp, err = userFeed.GetActivitiesWithRanking(
		context.TODO(),
		"popularity",
		stream.WithActivitiesLimit(5),
	)
	if err != nil {
		panic(err)
	}

// Get activities from 5 to 10
$results = $userFeed1->getActivities(5, 5);

# Get the 5 activities added after last_activity 
$options = ['id_lt' => $last_activity_id];
$results = $userFeed1->getActivities(0, 5, $options);

# Get the 5 activities added before last_activity 
$options = ['id_gt' => $last_activity_id];
$results = $userFeed1->getActivities(0, 5, $options);

// Get 5 enriched activities - using limit, offset, enrich - and sorted by rank (Ranked Feeds Enabled):
$options = ['ranking' => 'popularity'];
$results = $userFeed1->getActivities(0, 5, $options, $enrich=true);

// Get activities from 5 to 10.
userFeed?.get(pagination: .limit(5) + .offset(5)) { result in /* ... */ }

// Get the 5 activities added after lastActivity.
userFeed?.get(pagination: .limit(5) + .lessThan(lastActivity.id)) { result in /* ... */ }

// Get the 5 activities added before lastActivity.
userFeed?.get(pagination: .limit(5) + .greaterThan(lastActivity.id)) { result in /* ... */ }

// Get activities sorted by rank (Ranked Feeds Enabled).
userFeed?.get(pagination: .limit(5), ranking: "popularity") { result in /* ... */ }

// Get the 5 activities and enrich them with reactions and collections.
userFeed?.get(enrich: true, pagination: .limit(5), includeReactions: [.own, .latest, .counts]) { result in /* ... */ }

// Get 5 activities with id less than the given UUID (Faster - Recommended!)
var response = await userFeed.getActivities(
 limit: 5,
 filter: Filter().idLessThan("e561de8f-00f1-11e4-b400-0cc47a024be0"));
// Get activities from 5 to 10 (Pagination-based - Slower)
response = await userFeed.getActivities(offset: 0, limit: 5);
// Get activities sorted by rank (Ranked Feeds Enabled):
response = await userFeed.getActivities(limit: 5, ranking: "popularity");

Parameters

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

Pagination

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.

Retrieve Feed Response Data

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

{
 results: [],
 next: '/api/v1.0/feed/<< feed_group >>/<< feed_id >>/?api_key=<< api_key >>&id_lt=<< next_activity_id >>&limit=<< activity_limit >>'
}

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.

Removing Activities

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.

// Remove an activity by its id
await feed.RemoveActivityAsync("e561de8f-00f1-11e4-b400-0cc47a024be0");

// Remove activities by their foreign_id
await feed.RemoveActivityAsync("run:1", true);

// Remove an activity by its id
user1.removeActivity("ACTIVITY_ID");

// Remove activities foreign_id 'run:1'
user1.removeActivity({foreignId: 'run:1'});

# Remove an activity by its id
user_feed_1.remove_activity('ACTIVITY_ID')

# Remove activities with foreign_id 'run:1'
user_feed_1.remove_activity('run:1', foreign_id=true)

# Remove an activity by its id
response = user_feed_1.remove_activity("e561de8f-00f1-11e4-b400-0cc47a024be0")

removed_activity_id = response["removed"]

# Remove activities with foreign_id 'run:1'
response = user_feed_1.remove_activity(foreign_id='run:1')
removed_foreign_id = response["removed"]

// Remove an activity by its id
userFeed.removeActivityByID("e561de8f-00f1-11e4-b400-0cc47a024be0").join();

// Remove activities with foreign_id 'run:1'
userFeed.removeActivityByForeignID("run:1").join();

// Remove an activity by its id
	_, err := userFeed.RemoveActivityByID(context.TODO(), "e561de8f-00f1-11e4-b400-0cc47a024be0")
	if err != nil {
		panic(err)
	}
	// Remove activities with foreign_id 'run:1'
	_, err = userFeed.RemoveActivityByForeignID(context.TODO(), "run:1")
	if err != nil {
		panic(err)
	}

// Remove an activity by its id
$userFeed1->removeActivity('e561de8f-00f1-11e4-b400-0cc47a024be0');

// Remove activities with foreign_id 'run:1'
$userFeed1->removeActivity('run:1', true)

// Remove an activity by its id.
userFeed?.remove(activityId: "50539e71-d6bf-422d-ad21-c8717df0c325")

// Remove activities foreign_id "run:1".
userFeed?.remove(foreignId: "run:1")

// Remove an activity by its id
 await user1.removeActivityById('ACTIVITY_ID');

// Remove activities foreign_id 'run:1'
 await user1.removeActivityByForeignId('run:1');

Updating Activities

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

var activity = new Activity("1", "like", "3")
{
  Time = DateTime.Now,
  ForeignId = "like:3"
};
activity.SetData("popularity", 100);

// first time the activity is added
await userFeed1.AddActivityAsync(activity);

// update the popularity value for the activity
activity.SetData("popularity", 10);

// send the update to the APIs
await client.Batch.UpdateActivityAsync(activity);

const now = new Date();

const activity = {
  "actor": "1",
  "verb":"like",
  "object": "3",
  "time": now.toISOString(),
  "foreign_id": "like:3",
  "popularity": 100,
};

// first time the activity is added
user1.addActivity(activity);

// update the popularity value for the activity
activity.popularity = 10;

// send the update to the APIs
client.updateActivities([activity]);

activity = {
 :actor => "1",
 :verb => "like",
 :object => "3",
 :time => DateTime.now,
 :foreign_id => "like:3",
 :popularity => 100
}

# first time the activity is added
user_feed_1.add_activity(activity)

# update the popularity value for the activity
activity[:popularity] = 10

# send the update to the APIs
client.update_activities([activity])

activity = {
  "actor": "1",
  "verb":"like",
  "object": "3",
  "time": datetime.datetime.utcnow(),
  "foreign_id": "like:3",
  "popularity": 100
}

# first time the activity is added
user_feed_1.add_activity(activity)

# update the popularity value for the activity
activity['popularity'] = 10

# send the update to the APIs
client.update_activities([activity])

Activity activity = Activity.builder()
    .actor("1")
    .verb("like")
    .object("3")
    .time(new Date())
    .foreignID("like:3")
    .extraField("popularity", 100)
    .build();

// first time the activity is added
userFeed.addActivity(activity).join();

// update the popularity value for the activity
activity = Activity.builder()
    .fromActivity(activity)
    .extraField("popularity", 10)
    .build();

client.batch().updateActivities(activity);

activity := stream.Activity{
		Actor:   "User:1",
		Verb:   "like",
		Object:  "Object:3",
		Time:   stream.Time{time.Now()},
		ForeignID: "like:3",
		Extra: map[string]any{
			"popularity": 100,
		},
	}

	// first time the activity is added
	_, err := userFeed.AddActivity(context.TODO(), activity)
	if err != nil {
		panic(err)
	}

	// update the popularity value for the activity
	activity.Extra["popularity"] = 10

	// send the update to the APIs
	_, err = client.UpdateActivities(context.TODO(), activity)
	if err != nil {
		panic(err)
	}

$now = new DateTime('now');
$activities = [];

$activity = [
  'actor' => 1,
  'verb' => 'tweet',
  'object' => 1,
  'time' => $now->format(DateTime::ISO8601),
  'foreign_id' => 'batch1',
  'popularity' => 100,
];

// add the activity to a feed
$userFeed1->addActivity(activity);

// change a field of the activity data
$activity['popularity'] = 10;

$activities = [$activity];

// update the activity
$client->updateActivities($activities);

// Create a custom activity with a `popularity` property.
let activity = Activity(actor: User.current!, verb: "like", object: "3", popularity: 100)

userFeed?.add(activity) { _ in
  activity.popularity = 10
  Client.shared.update(activities: [activity]) { result in /* ... */ }
}

final now = DateTime.now();

final activity = Activity(
 actor: "1",
 verb: "like",
 object: "3",
 time: now,
 foreignId: "like:3",
 extraData: {
 'popularity': 100,
});

// first time the activity is added
final like = await user1.addActivity(activity);

// send the update to the APIs
user1.updateActivityById(id: like.id!,
// update the popularity value for the activity
set: {
 'popularity': 10,
});

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.

Activity Partial Update

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).

// partial update by activity ID
var set = new Dictionary<string, object>();
set.Add("product.price", 19.99);
set.Add("product.price", new Dictionary<string, string="">()
  {
     {"facebook", "..."},
     {"twitter", "..."}
  });
var unset = new[]{"daily_likes", "popularity"};
await client.ActivityPartialUpdateAsync("54a60c1e-4ee3-494b-a1e3-50c06acb5ed4", null, set, unset);

// partial update by foreign ID
var foreignIdTime = new ForeignIdTime("product:123", DateTime.Parse("2016-11-10T13:20:00.000000"));
await client.ActivityPartialUpdate(null, foreignIDTime, set, unset);

// partial update by activity ID
client.activityPartialUpdate({
 id: '54a60c1e-4ee3-494b-a1e3-50c06acb5ed4',
 set: {
  'product.price': 19.99,
  'shares': {
   'facebook': '...',
   'twitter': '...'
  },
 },
 unset: [
  'daily_likes',
  'popularity'
 ]
})

// partial update by foreign ID
client.activityPartialUpdate({
 foreign_id: 'product:123',
 time: '2016-11-10T13:20:00.000000',
 set: {
  ...
 },
 unset: [
  ...
 ]
})

# partial update by activity ID
client.activity_partial_update(
 id='54a60c1e-4ee3-494b-a1e3-50c06acb5ed4',
 set={
  'product.price': 19.99,
  'shares': {
   'facebook': '...',
   'twitter': '...'
  },
 },
 unset=[
  'daily_likes',
  'popularity'
 ]
)

# partial update by foreign ID
client.activity_partial_update(
 foreign_id='product:123',
 time='2016-11-10T13:20:00.000000',
 set={ ... },
 unset=[ ... ],
)

# partial update by activity ID
client.activity_partial_update(
 id: '54a60c1e-4ee3-494b-a1e3-50c06acb5ed4',
 set: {
  'product.price': 19.99,
  'shares': {
   'facebook': '...',
   'twitter': '...'
  },
 },
 unset: [
  'daily_likes',
  'popularity'
 ]
)

# partial update by foreign ID
client.activity_partial_update(
 foreign_id: 'product:123',
 time: '2016-11-10T13:20:00.000000',
 set: {
  ...
 },
 unset: [
  ...
 ]
)

$set = [
  "product.name" => "boots",
  "product.price" => 7.99,
  "popularity" => 1000,
  "foo" => ["bar" => ["baz" => "qux"]],
];
$unset = ["product.color"];

$this->client->doPartialActivityUpdate($activity['id'], null, null, $set, $unset);
// OR
$this->client->doPartialActivityUpdate(null, $activity['foreign_id'], $activity['time'], $set, $unset);

// prepare the set operations
Map<string, object=""> set = new ImmutableMap.Builder<string, object="">()
    .put("product.price", 19.99)
    .put("shares", new ImmutableMap.Builder<string, object="">()
        .put("facebook", "...")
        .put("twitter", "...")
        .build())
    .build();
// prepare the unset operations
String[] unset = new String[] { "daily_likes", "popularity" };

// partial update by activity ID
String id = "54a60c1e-4ee3-494b-a1e3-50c06acb5ed4";
client.updateActivityByID(id, set, unset).join();

// partial update by foreign ID
String foreignID = "product:123";
Date timestamp = new Date();
client.updateActivityByForeignID(foreignID, timestamp, set, unset).join();</string,></string,></string,>

// partial update by activity ID

	// prepare the set operations
	set := map[string]any{
		"product.price": 19.99,
		"shares": map[string]any{
			"facebook": "...",
			"twitter": "...",
		},
	}
	// prepare the unset operations
	unset := []string{"daily_likes", "popularity"}

	id := "54a60c1e-4ee3-494b-a1e3-50c06acb5ed4"
	_, err := client.UpdateActivityByID(context.TODO(), id, set, unset)
	if err != nil {
		panic(err)
	}

	// partial update by foreign ID
	foreignID := "product:123"
	timestamp := stream.Time{ /*...*/ }
	_, err := client.UpdateActivityByForeignID(context.TODO(), foreignID, timestamp, set, unset)
	if err != nil {
		panic(err)
	}

Client.shared.updateActivity(typeOf: ProductActivity.self,
               setProperties: ["product.price": 19.99, 
                       "shares": ["facebook": "...", "twitter": "..."]],
               unsetProperties: ["daily_likes", "popularity"],
               activityId: "54a60c1e-4ee3-494b-a1e3-50c06acb5ed4") { result in /* ... */ }

Client.shared.updateActivity(typeOf: ProductActivity.self,
               setProperties: [...],
               unsetProperties: [...],
               foreignId: "product:123",
               time: "2016-11-10T13:20:00.000000".streamDate!) { result in /* ... */ }

// partial update by activity ID
await user1.updateActivityById(id: exercise.id!, set: {
 'course.distance': 12,
 'shares': {
  'facebook': '...',
  'twitter': '...',
 },
}, unset: [
 'location',
 'participants'
]);

// partial update by foreign ID
user1.updateActivityByForeignId(
 foreignId: 'product:123',
 time: DateTime.parse(('2016-11-10T13:20:00.000000'),
 set: {
  ...
 },
 unset: [
  ...
 ]
);

Parameters

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:

{
  "id": "...", "actor": "...", "object": "...", "verb": "...", "foreign_id": "...",
  "product": {
    "sku": 12345,
    "price": {
      "eur": 7.99,
      "usd": 9.99
    },
    "name": "shoes",
    "popularity": 9000
  }
}

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:

{
  "set": {
    "product.price.eur": 8.99,
    "product.price.gbp": 6.99,
    "product.available": {
      "blue": 100,
      "black": 300
    },
    "facebook_page": "..."
  },
  "unset": [
    "product.price.usd",
    "popularity"
  ]
}

Batching Partial Updates

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:

# Update by ID
client.activities_partial_update([
  {
   id: "ACTIVITY_ID",
   set: {
    "key": "new-value"
   },
   unset: [ "removed", "keys" ]
  },
  {
   id: "ACTIVITY_ID",
   set: {
    "foo": "bar",
    "baz": "quux"
   },
   unset: [ "removed", "keys" ]
  }
 ])

# Update by foreign ID and timestamp
client.activities_partial_update([
 {
  foreign_id: "stroll:1",
  time: '2016-11-10T13:20:00.000000',
  set: {
   "key": "new-value"
  },
  unset: [ "removed", "keys" ]   
 },
 {
  foreign_id: "stroll:2",
  time: '2017-11-10T13:20:00.000000',
  set: {
   "foo": "bar",
   "baz": "quux"
  },
  unset: [ "removed", "keys" ]
 }
])

changesetA := stream.NewUpdateActivityRequestByID(
		"907a8010-1d84-11e9-9457-9cb6d0925edd",
		map[string]any{
			"key": "new-value",
		},
		[]string{"removed", "keys"},
	)
	changesetB := stream.NewUpdateActivityRequestByID(
		"de88ed3c-1d98-11e9-9457-9cb6d0925edd",
		map[string]any{
			"foo": "bar",
			"baz": "quux",
		},
		[]string{"removed", "keys"},
	)
	changesetC := stream.NewUpdateActivityRequestByForeignID(
		"stroll:1",
		stream.Time{ /*...*/ },
		map[string]any{
			"key": "new-value",
		},
		[]string{"removed", "keys"},
	)
	changesetD := stream.NewUpdateActivityRequestByForeignID(
		"stroll:2",
		stream.Time{ /*...*/ },
		map[string]any{
			"foo": "bar",
			"baz": "quux",
		},
		[]string{"removed", "keys"},
	)
	_, err := client.PartialUpdateActivities(context.TODO(), changesetA, changesetB)
	if err != nil {
		panic(err)
	}
	_, err := client.PartialUpdateActivities(context.TODO(), changesetC, changesetD)
	if err != nil {
		panic(err)
	}

$payload = [
  [
    "id" => $act1["id"],
    "set" => ["popularity" => 999],
    "unset" => ['new'],
  ],
  [
    "id" => $act2["id"],
    "set" => ["popularity" => 5],
  ],
];
$this->client->batchPartialActivityUpdate($payload);

Uniqueness & Foreign IDs

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:

var firstActivity = new Activity("1", "like", "3")
{
  Time = DateTime.UtcNow,
  ForeignId = "like:3"
};

var firstActivityID = (await userFeed1.AddActivityAsync(firstActivity)).Id;

var secondActivity = new Activity("1", "like", "3")
{
  Time = DateTime.UtcNow,
  ForeignId = "like:3"
};
secondActivity.SetData("extra", "extra_value");

var secondActivityID = (await userFeed1.AddActivityAsync(secondActivity)).Id;

// The unique combination of foreign_id and time ensure that both
// activities are unique and therefore the first_activity_id != second_activity_i

const first_activity = {
 actor: 1,
 verb: 'add',
 object: '1',
 foreign_id: 'activity_1'
 time: new Date().toISOString()
};

// Add activity to activity feed:
const { id: first_activity_id } = await user_feed_1.addActivity(first_activity);

const second_activity = {
 actor: 1,
 verb: 'add',
 object: '1',
 foreign_id: 'activity_2'
 time: new Date().toISOString()
};

const { id: second_activity_id } = await user_feed_1.addActivity(second_activity);

from datetime import datetime

first_activity = {
  "actor": "1",
  "verb":"like",
  "object": "3",
  "time":datetime.utcnow(),
  "foreign_id": "like:3"
}
first_activity_id = user_feed_1.add_activity(first_activity)['id']

second_activity = {
  "actor": "1",
  "verb":"like",
  "object": "3",
  "time": datetime.utcnow(),
  "extra": "extra_value",
  "foreign_id": "like:3"
}
second_activity_id = user_feed_1.add_activity(second_activity)['id']

# The unique combination of foreign_id and time ensure that both
# activities are unique and therefore the first_activity_id != second_activity_id

first_activity = {
 :actor => "1",
 :verb => "like",
 :object => "4",
 :time => DateTime.now,
 :foreign_id => "like:3"
}
first_activity_id = user_feed_1.add_activity(first_activity)['id']

second_activity = {
 :actor => "1",
 :verb => "like",
 :object => "4",
 :time => DateTime.now,
 :foreign_id => "like:3"
}
second_activity_id = user_feed_1.add_activity(second_activity)['id']

# The unique combination of foreign_id and time ensure that both
# activities are unique and therefore the first_activity_id != second_activity_id

Activity firstActivity = userFeed.addActivity(Activity.builder()
    .actor("1")
    .verb("like")
    .object("3")
    .time(new Date())
    .foreignID("like:3")
    .build()).join();
Activity secondActivity = userFeed.addActivity(Activity.builder()
    .actor("1")
    .verb("like")
    .object("3")
    .time(new Date())
    .extraField("extra", "extra_value")
    .foreignID("like:3")
    .build()).join();
// The unique combination of foreign_id and time ensure that both
// activities are unique and therefore the firstActivity ID != secondActivity ID

now := time.Now()
	firstActivity, err := userFeed.AddActivity(context.TODO(), stream.Activity{
		Actor:   "1",
		Verb:   "like",
		Object:  "3",
		Time:   stream.Time{now},
		ForeignID: "like:3",
	})
	if err != nil {
		panic(err)
	}
	secondActivity, err := userFeed.AddActivity(context.TODO(), stream.Activity{
		Actor: "1",
		Verb:  "like",
		Object: "3",
		Time:  stream.Time{now},
		Extra: map[string]interface{}{
			"extra": "extra_value",
		},
		ForeignID: "like:3",
	})
	if err != nil {
		panic(err)
	}
	// foreign ID and time are the same for both activities
	// hence only one activity is created and first and second IDs are equal
	// firstActivity.ID == secondActivity.ID

let firstActivity = Activity(actor: User.current!, verb: "add", object: "1", foreignId: "activity_1", time: Date())

// Add activity to activity feed:
var firstActivityId: String?
userFeed?.add(firstActivity) { result in
  let addedActivity = try! result.get()
  firstActivityId = addedActivity.id 
}

let secondActivity = Activity(actor: User.current!, verb: "add", object: "1", foreignId: "activity_2", time: Date())

var secondActivityId: String?
userFeed?.add(secondActivity) { result in
  let addedActivity = try! result.get()
  secondActivityId = addedActivity.id 
}

/// The unique combination of `foreignId` and `time` ensure that both
/// activities are unique and therefore the `firstActivityId != secondActivityId`

final first_activity = Activity(
 actor: '1',
 verb: 'add',
 object: '1',
 foreignId: 'activity_1',
 time: DateTime.now());

// Add activity to activity feed:
final firstActivityAdded = await user1.addActivity(first_activity);

final second_activity = Activity(
 actor: '1',
 verb: 'add',
 object: '1',
 foreignId: 'activity_2',
 time: DateTime.now());

final secondActivityAdded = await user1.addActivity(second_activity);

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.

GDPR-compliant actor discarding

Since the Feeds API doesn’t require users there’s no user-to-user blocking. However, in order to stay GDPR compliant there’s support for discarding actors when reading a feed. This leaves it up to the customer to keep track of which users have blocked other users.

# userA has blocked userB and userC
feed = client.feed("user", "userA")
results = feed.get(discard_actors=",".join(["userB", "userC"]))

curl --location 'https://eu-west-api.stream-io-api.com/api/v1.0/enrich/feed/feed_group/feed_id?api_key=APIKEY&limit=25&offset=0&withRecentReactions=true&recentReactionsLimit=25&discard_actors=userA%2CSU%3AuserB' \
--header 'Stream-Auth-Type: jwt' \
--header 'Authorization: TOKEN' \
--header 'Content-Type: application/json' \
--data ''

Automatic Activity Hiding

It’s possible to have the Feeds API automatically hide activities older than X days/months/years. This is an app-level setting, please contact support if you wish to have it enabled.