Official Clients

Official clients are currently available for a number of languages:

• 

  Ruby

• 

  JS

• 

  Python

• 

  PHP

• 

  Java

• 

  Go

• 

  .Net

Community Clients

The community also contributed clients for Scala and Elixir:

• 

  Scala

• 

  Elixir

If you want to build your own client, head over to the REST API documentation.

Framework Integrations

Stream makes it a breeze to integrate with a number of popular frameworks. If you're new to Stream we recommend starting out with the lower level clients.

• 

  Django

• 

  Rails

• 

  Laravel

• 

  Doctrine

• 

  NodeJS

• 

  Zend

Community Framework Projects

The community also contributed the following example projects:

• 

  CakePHP 3.x

Let's get set up! First, install the client as specified below:

// install directly with gem
gem install "stream-ruby"

// or add this to your Gemfile and then run bundler
gem "stream-ruby"

// install via npm
npm install getstream --save

// install using bower
bower install getstream

// latest build is available at this link as well
https://raw.githubusercontent.com/GetStream/stream-js/master/dist/js/getstream.js

pip install stream-python

// install using composer
composer require get-stream/stream

// Add the following dependency and repository to your pom.xml file

<dependency>
    <groupId>io.getstream.client</groupId>
    <artifactId>stream-repo-apache</artifactId>
    <version>1.2.0</version>
</dependency>

// install from the command line
go get gopkg.in/GetStream/stream-go2.v1

// import it in your code
import "gopkg.in/GetStream/stream-go2.v1"

// install via Nuget

nuget install stream-net

To instantiate the client you need an API key and secret. You can find the key and secret on the dashboard.

# Instantiate a new client
require 'stream'
client = Stream::Client.new('YOUR_API_KEY', 'API_KEY_SECRET', :location => 'us-east')
# Find your API keys here https://getstream.io/dashboard/

var stream = require('getstream');
// Instantiate a new client (server side)
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET', 'APP_ID');
// Instantiate a new client (client side)
client = stream.connect('YOUR_API_KEY', null, 'APP_ID');
// Find your API keys here https://getstream.io/dashboard/

# Instantiate a new client
import stream
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET', location='us-east')
# Find your API keys here https://getstream.io/dashboard/

// Instantiate a new client
$client = new GetStream\Stream\Client('YOUR_API_KEY', 'API_KEY_SECRET');
// Find your API keys here https://getstream.io/dashboard/

// import io.getstream.client.config.ClientConfiguration;
// import io.getstream.client.model.feeds.Feed;

ClientConfiguration streamConfig = new ClientConfiguration();
StreamClient streamClient = new StreamClientImpl(streamConfig, "YOUR_API_KEY", "API_KEY_SECRET");

import (
    stream "gopkg.in/GetStream/stream-go2.v1"
)

client, err := stream.NewClient(
    "YOUR_API_KEY",
    "API_KEY_SECRET",
)

// Instantiate a new client
var client = new StreamClient("YOUR_API_KEY","API_KEY_SECRET");

chris = client.feed('user', 'chris')

# Add an Activity; message is a custom field - tip: you can add unlimited custom fields!
activity_data = { :actor => 'chris', :verb => 'add', :object => 'picture:10', :foreign_id => 'picture:10', :message => 'Beautiful bird!' }
chris.add_activity(activity_data);

# Create a following relationship between Jack's "timeline" feed and Chris' "user" feed:
jack = client.feed('timeline', 'jack')
jack.follow('user', 'chris')

# Read Jack's timeline and Chris' post appears in the feed:
activities = jack.get(:limit => 10)

# Remove an Activity by referencing it's foreign_id
chris.remove_activity('picture:10', foreign_id=true)

var chris = client.feed('user', 'chris');

// Add an Activity; message is a custom field - tip: you can add unlimited custom fields!
chris.addActivity({
  actor: 'chris',
  verb: 'add',
  object: 'picture:10',
  foreign_id: 'picture:10',
  message: 'Beautiful bird!'
}).then(
  null, // nothing further to do
  function(err) {
    // Handle or raise the Error.
  }
);

// Create a following relationship between Jack's "timeline" feed and Chris' "user" feed:
var jack = client.feed('timeline', 'jack');
jack.follow('user', 'chris').then(
  null, // nothing further to do
  function(err) {
    // Handle or raise the Error.
  }
);


// Read Jack's timeline and Chris' post appears in the feed:
jack.get({ limit: 10 }).then(function(results) {
  var activityData = results; // work with the feed activities
},function(err) {
    // Handle or raise the Error.
});

// Remove an Activity by referencing it's Foreign Id:
chris.removeActivity({ foreignId: 'picture:10' }).then(
  null, // nothing further to do
  function(err) {
    // Handle or raise the Error.
  }
);

chris = client.feed("user", "chris")

# Add an Activity; message is a custom field - tip: you can add unlimited custom fields!
chris.add_activity({
  "actor": "chris",
  "verb": "add",
  "object": "picture:10",
  "foreign_id": "picture:10",
  "message": "Beautiful bird!"
})

# Create a following relationship between Jack's "timeline" feed and Chris' "user" feed:
jack = client.feed("timeline", "jack")
jack.follow('user', "chris")

# Read Jack's timeline and Chris' post appears in the feed:
activities = jack.get(limit=10)["results"]

# Remove an Activity by referencing it's foreign_id
chris.remove_activity(foreign_id="picture:10")

$chris = $client->feed('user', 'chris');

// Add an Activity; message is a custom field - tip: you can add unlimited custom fields!
$data = [
  "actor" => "chris",
  "verb" => "add",
  "object" => "picture:10",
  "foreign_id" => "picture:10",
  "message" => "Beautiful bird!",
];

$chris->addActivity($data);

// Create a following relationship between Jack's "timeline" feed and Chris' "user" feed:
$jack = $client->feed('timeline', 'jack');
$jack->followFeed('user', 'chris');

// Read Jack's timeline and Chris' post appears in the feed:
$activities = $jack->getActivities(10)['results'];

// Remove the activity by referencing the foreign_id you provided:
$chris->removeActivity("picture:10", true);

Feed chrisUserFeed = streamClient.newFeed("user", "chris");

// Create an Activity service
FlatActivityServiceImpl<SimpleActivity> flatActivityService = chrisUserFeed.newFlatActivityService(SimpleActivity.class);

// Add an Activity; message is a custom field - tip: you can add unlimited custom fields!
SimpleActivity activity = new SimpleActivity();
activity.setActor("chris");
activity.setObject("picture:10");
activity.setVerb("add");
SimpleActivity response = flatActivityService.addActivity(activity);

// Create a following relationship between Jack's "timeline" feed and Chris' "user" feed:
Feed jackTimeline = streamClient.newFeed("timeline", "jack");
jackTimeline.follow('user', 'chris');

// Read Jack's timeline and Chris' post appears in the feed:
List<SimpleActivity> jackTimeline = jackTimeline.newFlatActivityService(SimpleActivity.class).getActivities(new FeedFilter.Builder()).getResults();

# Remove an Activity by referencing it's foreign_id
chrisUserFeed.deleteActivityByForeignId("picture:10");

chris := client.FlatFeed("user", "chris")

// Add an Activity; message is a custom field - tip: you can add unlimited custom fields!
_, err := chris.AddActivity(stream.Activity{
    Actor:     "chris",
    Verb:      "add",
    Object:    "picture:10",
    ForeignID: "picture:10",
    Extra: map[string]interface{}{
        "message": "Beautiful bird!",
    },
})
if err != nil {
    panic(err)
}

// Create a following relationship between Jack's "timeline" feed and Chris' "user" feed:
jack := client.FlatFeed("timeline", "jack")
err = jack.Follow(chris)
if err != nil {
    panic(err)
}

// Read Jack's timeline and Chris' post appears in the feed:
resp, err := jack.GetActivities(stream.WithActivitiesLimit(10))
if err != nil {
    panic(err)
}
for _, activity := range resp.Results {
    // ...
}

// Remove an Activity by referencing it's foreign_id
err = chris.RemoveActivityByForeignID("picture:10")
if err != nil {
    panic(err)
}

var chrisFeed = client.Feed("user", "chris");

// Add an Activity; message is a custom field - tip: you can add unlimited custom fields!
var activity = new Activity("chris", "add", "picture:10")
{
    ForeignId = "picture:10"
};
activity.SetData("message", "Beautiful bird!");

chrisFeed.AddActivity(activity);

// Create a following relationship between Jack's "timeline" feed and Chris' "user" feed:
jackTimeline = client.Feed("timeline", "jack");
jackTimeline. FollowFeed("user", "chris");

// Read Jack's timeline and Chris' post appears in the feed:
var activities = await jackTimeline.GetActivities(0, 10);

// Remove the activity by referencing the foreign_id you provided:
chrisFeed.RemoveActivity("picture:10", true);

That was a lot of information all at once. The getting started provides a more detailed and interactive explanation. Keep on scrolling to read the full documentation.

Adding Activities: Basic

Adding an activity in it’s simplest form means passing an object with the following basic properties:

• Actor
• Verb
• Object
• Target (Optional)
• 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)
• Target: "Places to Visit" (Board:1)
• 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
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", :target => "Board:1"}
activity_response = user_feed_1.add_activity(activity_data)

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

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

// Add an activity to the feed
var activity = {actor: 'User:1', verb: 'pin', object: 'Place:42', target: 'Board:1'};

// Asynchronous methods return Promise since v3.0.0
user1.addActivity(activity)
    .then(function(data) { /* on success */ })
    .catch(function(reason) { /* on failure, reason.error contains an explanation */ });

# 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", "target": "Board:1"}
activity_response = user_feed_1.add_activity(activity_data)

// 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",
    "target"=>"Board:1",
];

$userFeed1->addActivity($data);

// Instantiate a feed object
Feed feed = streamClient.newFeed("user", "1");

// Create an activity service
FlatActivityServiceImpl<SimpleActivity> flatActivityService = feed.newFlatActivityService(SimpleActivity.class);

// Add an activity to the feed, where actor, object and target are references to objects (`Eric`, `Hawaii`, `Places to Visit`)
SimpleActivity activity = new SimpleActivity();
activity.setActor("User:1");
activity.setObject("Place:42");
activity.setVerb("pin");
activity.setTarget("Board:1");
SimpleActivity response = flatActivityService.addActivity(activity);

// Instantiate a feed object
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 := stream.Activity{
    Actor:  "User:1",
    Verb:   "pin",
    Object: "Place:42",
    Target: "Board:1",
}
_, err := userFeed.AddActivity(activity)
if err != nil {
    panic(err)
}

// 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");
userFeed1.AddActivity(activity);

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

Fields

Custom fields

In addition to the mandatory and recommended fields, extra custom fields may be added to an activity. Let's look at a more expressive example:

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

// Create a bit more complex activity
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] }
};
user1.addActivity(activity)
    .then(function(data) { /* on success */ })
    .catch(function(reason) { /* on failure */ });

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
$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);

// You can add custom data to your activities.
//
// Here's an example on how to do it:
// https://github.com/GetStream/stream-java/blob/master/stream-repo-apache/src/test/java/io/getstream/client/apache/example/mixtype/MixedType.java

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

// 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 string[] { "Thierry", "Tommaso" };

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

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

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 (128KB) and must not contain blob/binary data (eg. 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:

{  
   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"
}

{  
   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"
}

{  
   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"
}

{  
   "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"
}

{  
   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"
}

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

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

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

// Remove an activity by its id
user1.removeActivity("e561de8f-00f1-11e4-b400-0cc47a024be0");
// Remove activities foreign_id 'run:1'
user1.removeActivity({foreignId: 'run:1'});

# 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
$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
feed.deleteActivity("e561de8f-00f1-11e4-b400-0cc47a024be0");

// Remove activities by their foreign_id
feed.deleteActivityByForeignId("run:1");

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

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

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

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

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

var now = new Date();

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

$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);

SimpleActivity activity = new SimpleActivity();
activity.setActor("actor");
activity.setObject("object");
activity.setTarget("target");
activity.setTime(new Date());
activity.setForeignId("foreign1");
activity.setVerb("verb");

StreamActivitiesResponse<SimpleActivity> response = flatActivityService.updateActivities(Collections.singletonList(activity));

response.getActivities(); // list of activities

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

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

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

// send the update to the APIs
err = userFeed.UpdateActivities(activity)
if err != nil {
    panic(err)
}

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

# 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.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({
  foreignID: '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(
  foreignID='product:123',
  time='2016-11-10T13:20:00.000000',
  set={ ... },
  unset=[ ... ],
)

# Not supported yet

// Not supported yet

// partial update by activity ID

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

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

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

// partial update by activity ID
var set = new GenericData();
set.SetData("product.price", 19.99);
set.SetData("product.price", new Dictionary<string, string>()
    {
         {"facebook", "..."},
         {"twitter", "..."}
    });
var unset = new string[]{"daily_likes", "popularity"};
await client.UpdateActivity("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.UpdateActivity(null, foreignIDTime, 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"
    ]
}

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 & foreign_id. See the example below for an overview:

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

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

// Add activity to activity feed:
var first_activity_id;
user_feed_1.addActivity(first_activity)
    .then(function(activity_response) {first_activity_id = activity_response.id;})
    .catch(function(error) { /* Handle error */ });

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

var second_activity_id;
user_feed_1.addActivity(second_activity)
    .then(function(activity_response) {second_activity_id = activity_response.id;})
    .catch(function(error) { /* Handle error */ });


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

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

now := time.Now()
firstActivity, err := userFeed.AddActivity(stream.Activity{
    Actor:     "1",
    Verb:      "like",
    Object:    "3",
    Time:      stream.Time{now},
    ForeignID: "like:3",
})
if err != nil {
    panic(err)
}
secondActivity, err := userFeed.AddActivity(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

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

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

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

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

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

Parameters

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

Passing both id_lt[e] and id_gt[e] is not supported.

Note on Aggregated Feeds: When using id_lte to paginate an aggregated feed, use the ID of the group that is returned from the API. Using an ID of an individual activity within the group will not work and result in an error.

Note on Custom Ranking: Sorting using a custom ranking formula is only available on paid plans.

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 >>&amp;id_lt=<< next_activity_id >>&amp;limit=<< activity_limit >>'
}

{
  "results": [],
  "next": "/api/v1.0/feed/<< feed_group >>/<< feed_id >>/?api_key=<< api_key >>&amp;id_lt=<< next_activity_id >>&amp;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.

Following relationships are a fundamental part of social networks and many other apps that feature feeds. They link one Feed to another and cause Activities added to a feed to appear in other any other feeds that follow it.

When an Activity is added to a feed, it is automatically added to any other feeds that follow the feed. This does not propagate further through the graph of following relationships. If your app requires that the Activity be added to other feeds, "to" field targetting or a batch activity add may be suitable.

The code example below shows you how to follow a feed:

# timeline:timeline_feed_1 follows user:user_42
timeline_feed_1 = client.feed('timeline', 'timeline_feed_1')
timeline_feed_1.follow('user', 'user_42')

# follow feed without copying the activities:
timeline_feed_1.follow('user', 'user_42', activity_copy_limit=0)

// timeline:timeline_feed_1 follows user:user_42:
timeline_feed_1.follow('user', 'user_42');

// Follow feed without copying the activities:
timeline_feed_1.follow('user', 'user_42', { limit: 0 });

# timeline:timeline_feed_1 follows user:user_42
timeline_feed_1.follow("user", "user_42")

# Follow feed without copying the activities
timeline_feed_1.follow("user", "user_42", activity_copy_limit=0)

// timeline:timeline_feed_1 follows user:user_42
$timeline1 = $client->feed('timeline', 'timeline_1');
$timeline1->follow('user', 'user_42');

// follow feed without copying the activities:
$timeline1->follow('user', 'user_42', 0)

// timeline:timeline_feed_1 follows user:user_42
Feed timeline_feed_1 = streamClient.newFeed("timeline", "timeline_feed_1");
timeline_feed_1.follow("user", "user_42");

// timeline:timeline_feed_1 follows user:user_42
user := client.FlatFeed("user", "user_42")
timeline := client.FlatFeed("timeline", "timeline_feed_1")
err := timeline.Follow(user)
if err != nil {
    panic(err)
}

// follow feed without copying the activities:
timeline.Follow(user, stream.WithFollowFeedActivityCopyLimit(20))

// timeline:timeline_feed_1 follows user:user_42
var timelineFeed1 = client.Feed("timeline", "timeline_feed_1");
await timelineFeed1.FollowFeed("user", "user_42");

// follow feed without copying the activities:
await timelineFeed1.FollowFeed("user", "user_42", 0);

Also take note that:

• Only Flat Feeds may be followed
• A Feed cannot follow itelf

By default, the most recent 300 existing activities in the target feed will be added to the follower feed (asynchronously), but this can be changed via the activity_copy_limit parameter.

Parameters

If you need to follow many feeds at once have a look at how to batch follow later in this document. If you need to run large imports, use our JSON import format.

Removes the following relationship with the feed specified in the target parameter. An example below:

# Stop following feed user_42
timeline_feed_1.unfollow('user', 'user_42')

# Stop following feed 42 but keep history of activities
timeline_feed_1.unfollow('user', 'user_42', keep_history=true)

// Stop following feed user_42 - purging history:
timeline_feed_1.unfollow('user', 'user_42');

// Stop following feed user_42 but keep history of activities:
timeline_feed_1.unfollow('user', 'user_42', { keepHistory: true });

# Stop following feed user_42
timeline_feed_1.unfollow("user", "user_42")

# Stop following feed user_42 but keep history of activities
timeline_feed_1.unfollow("user", "user_42", keep_history=True)

// Stop following feed user_42
$timelineFeed1->unfollow('user', 'user_42');

// Stop following feed user_42 but keep history of activities:
$timelineFeed1->unfollow('user', 'user_42', true);

// Stop following feed user_42
timeline_feed_1.unfollow("user", "user_42");

// Stop following feed user_42 keeping the history
timeline_feed_1.unfollow("user", "user_42", true);

// user := client.FlatFeed("user", "42")

// Stop following feed user:user_42
err := timeline.Unfollow(user)
if err != nil {
    panic(err)
}
// Stop following feed user:user_42 but keep history of activities
err = timeline.Unfollow(user, stream.WithUnfollowKeepHistory(true))
if err != nil {
    panic(err)
}

var timelineFeed1 = client.Feed("timeline", "timeline_feed_1");
// Stop following feed user_42
await timelineFeed1.UnfollowFeed("user", "user_42");

// Stop following feed 42 but keep history of activities
await timelineFeed1.UnfollowFeed("user", "user_42", true);

Existing Activities in the feed that originated in the target, no longer followed, feed will be purged (asynchronously) unless the keep_history parameter is provided.

Parameters

Returns a paginated list of the given feed's followers. Code example below:

# list followers
user_feed_1.followers(0, 10)

// List followers
user1.followers({limit: '10', offset: '10'});

# list followers
user_feed_1.followers(offset=0, limit=10)

// list followers
$userFeed1->followers(0, 10);

// Retrieve first 10 followers of a feed
FeedFilter filter = new FeedFilter.Builder().withLimit(10).build();
List<FeedFollow> followersPaged = feed.getFollowers(filter);

// list followers
resp, err := userFeed.GetFollowers(stream.WithFollowersOffset(0), stream.WithFollowersLimit(10))
for _, follower := range resp.Results {
    fmt.Println(follower.FeedID, "->", follower.TargetID)
    // ...
}

await userFeed1.Followers(0, 10);

The followers returned by the API are sorted reverse chronologically, according to the time the follow relationship was created.

Parameters

Response data

{results: [
    {
      feed_id: 'conversation2:test',
      target_id: 'conversation2:user_2',
      created_at: '2018-01-19T09:35:17.817332Z'
    }
  ],
  duration: "1.92ms"
}

{
  "results"': [
    {
      "feed_id": "conversation2:test",
      "target_id": "conversation2:user_2",
      "created_at": "2018-01-19T09:35:17.817332Z"
    }
  ],
  "duration": "1.92ms"
}

Returns a paginated list of the feeds which are followed by the feed. Code example below:

# Retrieve 10 feeds followed by user_feed_1
user_feed_1.following(10)

# Retrieve 10 feeds followed by user_feed_1 starting from the 11th
user_feed_1.following(10, 10)

# Check if user_feed_1 follows specific feeds
user_feed_1.following(0, 2, filter=['user:42', 'user:43'])

// Retrieve last 10 feeds followed by user_feed_1
user1.following({offset: 0, limit: 10});

// Retrieve 10 feeds followed by user_feed_1 starting from the 11th
user1.following({offset: 10, limit: 10});

// Check if user1 follows specific feeds
user1.following({offset: 0, limit: 2, filter: ['user:42', 'user:43']})

# Retrieve last 10 feeds followed by user_feed_1
user_feed_1.following(offset=0, limit=10)

# Retrieve 10 feeds followed by user_feed_1 starting from the 11th
user_feed_1.following(offset=10, limit=10)

# Check if user_feed_1 follows specific feeds
user_feed_1.following(offset=0, limit=2, feeds=['user:42', 'user:43'])

// Retrieve 10 feeds followed by $userFeed1
$userFeed1->following(0, 10);

// Retrieve 10 feeds followed by $userFeed1 starting from the 10th (2nd page)
$userFeed1->following(10, 10);

// Check if $userFeed1 follows specific feeds
$userFeed1->following(0, 2, ['user:42', 'user:43']);

// Retrieve first 10 followers of a feed
FeedFilter filter = new FeedFilter.Builder().withLimit(10).build();
List<FeedFollow> followingPaged = feed.getFollowing(filter);

// Retrieve last 10 feeds followed by user_feed_1
resp, err := userFeed.GetFollowing(stream.WithFollowingOffset(0), stream.WithFollowingLimit(10))
if err != nil {
    panic(err)
}

// Retrieve 10 feeds followed by user_feed_1 starting from the 11th
resp, err = userFeed.GetFollowing(stream.WithFollowingOffset(10), stream.WithFollowingLimit(10))
if err != nil {
    panic(err)
}

// Check if user_feed_1 follows specific feeds
resp, err = userFeed.GetFollowing(
    stream.WithFollowingOffset(0),
    stream.WithFollowingLimit(2),
    stream.WithFollowingFilter("user:42", "user:43"),
)
if err != nil {
    panic(err)
}

// Retrieve last 10 feeds followed by userFeed1
await userFeed1.Following(0, 10);

// Retrieve 10 feeds followed by userFeed1 starting from the 11th
await userFeed1.Following(10,  10);

// Check if user1 follows specific feeds
await userFeed1.Following(0, 2, new string[] { "user:42", "user:43" });

The followed feeds returned by the API are sorted reverse chronologically, according to the time the follow relationship was created.

Parameters

Response data

{results: [
     {
       feed_id: 'conversation2:test',
       target_id: 'conversation2:user_2',
       created_at: '2018-01-19T09:35:17.817332Z',
       updated_at: null
     }
   ],
  duration: '1.92ms'
}

{'results': [
     {
       'feed_id': 'conversation2:test',
       'target_id': 'conversation2:user_2',
       'created_at': '2018-01-19T09:35:17.817332Z',
       'updated_at': None
     }
   ],
  'duration': '1.92ms'
}

Feed Types

There are 3 feed types:

• Flat
• Aggregated
• Notification

Based on these 3 basic feed types you can create your own feed groups.

"Which Feed Groups Should I Create?"

We recommend that you create different feed groups for adding activities, and for consuming activities.

Flat are the only feeds that can be followed, and therefore are a good type to setup for adding activities. Flat can also be used to consume activities from other feeds - in a "timeline"-like manner.

Aggregated are good for consuming activities in an "aggregated"-like manner. You cannot follow an aggregated feed, but you may on occasion want to add activities to one.

The Notification type makes it easy to add notifications to your app. Notifications cannot be followed by other feeds - but you can write directly to a Notification feed.

Take for example that you are building a music app like Spotify.

You might set up the following feeds:

• "notification" (Notification): Displaying notifications from anything a user is following.
• "user" (Flat): Adding activities from a user that can be followed.
• "artist" (Flat): Adding activities from an artist that can be followed.
• "playlist" (Flat): Adding activities from a playlist that can be followed.
• "timeline" (Flat): Displaying "user", "artist", or "playlist" activities.

"How Do I Create Feeds?"

New feeds can be created in the Feeds section of the Dashboard.

By default, we setup four feed groups for your project:

• "user" (Type: Flat)
• "timeline" (Type: Flat)
• "timeline_aggregated" (Type: Aggregated)
• "notification" (Type: Notification)

These four groups cover the average use-cases for most applications.

Create new feed groups based on the flat type in the dashboard.

Options

There are several options you can configure:

• Eric followed 10 people
• Julie and 14 others like your photo

You can create new aggregated feed groups in the dashboard.

Options

There are several options you can configure for aggregated feeds. The most important setting is the aggregation format. This format determines how activities are grouped together.

How aggregated feeds work

When you insert an activity to an aggregated feed we apply the aggregation format. The aggregation format + the activity's data lead to a value for the "group". This group is used to combine the activities.

Aggregation Format Syntax

The following variables are available:

• verb the activity verb as it is send to the APIs (e.g. "like")
• time the activity creation date and time (or the value sent to APIs)
• object the activity object as it is sent to the APIs (e.g. Item:13)
• target the activity target (e.g. Place:9)
• actor the activity actor (e.g. User:9)
• feed.group the feed group name (e.g. if the feed is "notification:123", feed.group is notification)
• feed.user_id the feed user id (e.g. if the feed is "notification:123", feed.user_id is 123))
• id the internal unique activity id. This will be unique so if you use this nothing will be aggregated. Use this when you don't want aggregation, but only the mark_read/mark_seen functionality.

In addition, you can use any of the custom values you've provided when adding the activity.

Here are some common examples of aggregation formats:

• Per actor, verb id and day:
  {{ actor }}_{{ verb }}_{{ time.strftime("%Y-%m-%d") }}
• Per target, verb id and day:
  {{ target }}_{{ verb }}_{{ time.strftime("%Y-%m-%d") }}
• Follows by actor, likes by target
  {% if verb == 'follow' %}{{ actor }}{% else %}{{ target }}{% endif %}_{{ verb }}_{{ time.strftime("%Y-%m-%d") }}

The aggregation rule uses the Jinja2 Template Syntax. Control structures like if and else are avaliable, as well as these filters: int, lower and strftime to format the time variable. The options for strftime are documented here. Please get in touch with support if you need help with your aggregation formula.

Example data

The data format in which Aggregated Feeds are returned differs from regular Flat Feeds.

At the top level of the JSON response the 'results' field contains an array of Activity Groups plus additional metadata about the feed. Within the results array, each Activity Group contains a count of Activities and unique 'actors' contained within the group.

          The example "aggregation_feed_retrieve_example_data" couldn't be loaded
 	  		

You can create new Notification Feed Groups in the dashboard.

Options

There are several options to configure:

Example data

Similar to Aggregated Feeds, the data format in which Notification Feeds are retrieved differs from regular Flat Feeds.

At the top level of the JSON response the 'results' field contains an array of Activity Groups, along with overall 'unseen' and 'unread' counts and other metadata about the feed. Within the results array, each Activity Group contains the additional status fields that indicate the group is seen/read.

          The example "notification_feed_retrieve_example_data" couldn't be loaded
 	  		

When reading the feed, set the mark_read and mark_seen parameter. The next time the feed is read, the seen and/or read status will be updated accordingly.

If passing IDs to mark_seen or mark_read, be sure to pass the ID of the activity group as returned by the API, not the IDs of individual activities.

Here's the example using the various clients:

# Mark all activities in the feed as seen
result = notification_feed.get(:limit=>5, :offset=>0, :mark_seen=>true)

# Mark some activities as read via specific Activity Group Ids
result = notification_feed.get(:limit=>5, :mark_read=>['activity_group_id_1', 'activity_group_id_2'])

// Mark all activities in the feed as seen
notificationFeed.get({mark_seen:true})
    .then(function(data) { /* on success */ })
    .catch(function(reason) { /* on failure */ });

// Mark some activities as read via specific Activity Group Ids
notificationFeed.get({mark_read: ['activityGroupIdOne', 'activityGroupIdTwo']})
    .then(function(data) { /* on success */ })
    .catch(function(reason) { /* on failure */ });

# Mark all activities in the feed as seen
results = notification_feed.get(mark_seen=True)['results']

# Mark some activities as read via specific Activity Group Ids
notification_feed.get(mark_read=[results[0]['id'], results[1]['id']])

# Mark all activities in the feed as seen
$options = ['mark_seen' => true];
$results = $notificationFeed->getActivities(0, 10, $options);

# Mark some activities as read via specific Activity Group Ids
$options = ['mark_read' => ['activity_group_id_1', 'activity_group_id_2']];
$results = $notificationFeed->getActivities(0, 10, $options);

// Mark all activities in the feed as seen and read
NotificationActivityServiceImpl<SimpleActivity> notificationActivityService = feed.newNotificationActivityService(SimpleActivity.class);
notificationActivityService.getActivities(new FeedFilter.Builder().build(), true, true);

// Mark one activity as read by its id
MarkedActivity marker = new MarkedActivity.Builder().withActivityId("e561de8f-00f1-11e4-b400-0cc47a024be0").build();
notificationActivityService.getActivities(new FeedFilter.Builder().build(), marker, new MarkedActivity.Builder().build());

notifications := client.NotificationFeed("notifications", "1")
// Mark all activities in the feed as seen
resp, err := notifications.GetActivities(stream.WithNotificationsMarkSeen(true))
if err != nil {
    panic(err)
}
for _, activity := range resp.Results {
    // ...
}
// Mark some activities as read via specific Activity Group Ids
resp, err = notifications.GetActivities(stream.WithNotificationsMarkRead(
    false,              // don't mark all
    groupID1, groupID2, //...
))

// Mark all activities in the feed as seen
var result = await notificationFeed.GetActivities(0, 5, null, ActivityMarker.Mark().AllSeen());

// Mark some activities as read via specific Activity Group Ids
var result = await notificationFeed.GetActivities(0, 5, null, ActivityMarker.Mark().Read(new string[] { "activity_group_id_1", "activity_group_id_2" }));

You'll often want to listen to feed changes in real-time. This is explained in the section on real-time updates.

Stream allows you to listen to feed changes in real-time. As a first step we need to generate a token to give your client side Javascript access to the feed. By default feed tokens will give both read and write permissions. You can also generate read only tokens.

# read + write token for feed user:1
token = client.feed('user', '1').token
# Generating tokens for client side usage
readonly_token = client.feed('user', '1').readonly_token

// read + write token for feed user:1
var token = client.feed('user', '1').token;
// creates a readonly token for feed user:1
var readonlyToken = client.feed('user', '1').getReadOnlyToken();

# read + write token for feed user:1
token = user_feed_1.token
# readonly token
readonly_token = user_feed_1.get_readonly_token()

// read + write token for feed user:1
$token = $userFeed1->getToken();

// creates a read-only token for feed user:1
$readonlyToken = $userFeed1->getReadonlyToken();

// read and write token for feed user:1
String token = userFeed1.getToken();

// readonly token
String readOnlyToken = userFeed1.getReadOnlyToken();

// read + write token for feed user:1
token := userFeed.RealtimeToken(false)
// readonly token
readonlyToken := userFeed.RealtimeToken(true)

Subscribing to changes in real-time is done via JavaScript using the stream-js client. If you are not using it already, you can obtain it here.

Once you have included the JavaScript client in your pages you can subscribe to real-time notifications this way:

<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/getstream/dist/js_min/getstream.js"></script>
<script type="text/javascript">
    var client = stream.connect('YOUR_API_KEY', null, 'SITE_ID');
    var user1 = client.feed('user', '1', '{{ user_feed_1.token }}');

    function callback(data) {
        console.log(data);
    }

    function successCallback() {
        console.log('now listening to changes in realtime');
    }

    function failCallback(data) {
        alert('something went wrong, check the console logs');
        console.log(data);
    }

    user1.subscribe(callback).then(successCallback, failCallback);
</script>

Stream returns the following data via the realtime endpoint:

  // Realtime notification data format
  {
      "data": {
          "deleted": "array activities",
          "new": "array activities",
          "feed": "the feed id",
          "app_id": "the app id",
          "published_at":"time in iso format",
      },
      "channel":"",
  }
  

Besides the realtime endpoint, you can also connect to Stream's Firehose via SQS or webhooks. This is helpful if you want to send push notifications or emails based on feed activity.

• SQS queues
• Webhooks

Stream can send all the updates on your feed group to an Amazon SQS queue you own. The Firehose makes it easy to extend Stream. It's often used to send push notifications or emails based on feed activity.

The real-time updates are:

• Published on an SQS queue you own
• Stored in the same queue
• Sent in JSON format and Base64 encoded

A list with the following properties for each item in the list:

Configuration

To configure an SQS queue go the dashboard and select the feed group for which you want to configure the SQS realtime transport. If you enable "Realtime Notifications" in the form you can open the advanced realtime configuration via the "Realtime Configuration" link. Now enable the SQS transport and configure your queues url, api key, and api secret. If you click the "Test SQS" button we will send a test request to your SQS queue and show any errors with the current configuration if found.

SQS permissions

Stream needs the right permissions on your SQS queue to be able to send realtime updates to it. If updates are not showing up in your queue add the following permission policy to the queue:

    
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "Stmt1459523779000",
                  "Effect": "Allow",
                  "Action": [
                      "sqs:GetQueueUrl",
                      "sqs:SendMessage",
                      "sqs:SendMessageBatch",
                      "sqs:GetQueueAttributes"
                  ],
                  "Resource": [
                      "arn:aws:sqs:region:acc_id:queue_name"
                  ]
              }
          ]
      }
    
  

Here's an example list of messages read from your SQS queue:

    
        [{
            "deleted":[],
            "new":[{"actor":"1","verb":"tweet","object":"1","target":null,"time":"2014-12-15T17:20:37.258","foreign_id":null,"id":"af781804-847e-11e4-8080-80012fb97b9e","tweet":"Hello world"}],
            "published_at":"2014-12-15T17:20:37.263518+00:00",
            "feed":"user:2",
            "app_id": "123"
        }],
        [{
            "deleted":["38f81366-847f-11e4-9c94-0cc47a024be0"],
            "new":[],
            "published_at":"2014-12-15T17:20:37.263518+00:00",
            "feed":"timeline:1",
            "app_id": "123"
        }]
    
  

Stream can send all the updates on your feed group to a webhook you manage. The Firehose makes it easy to extend Stream. It's often used to send push notifications or emails based on feed activity.

Real-time updates are:

• Sent with a POST request
• Data is serialized to JSON
• Single request can contain multiple updates (up to 100 activities per push)

You are responsible for the security of the webhook endpoint. We suggest that you use HTTPS in combination with HTTP simple authentication. (e.g. https://username:password@domain.tld/path/to/webhook/)

Configuration and verification

Webhook url's can be configured directly on the dashboard. Navigate to the app overview page and select the feed group for which you want to configure webhooks. Once "Realtime Notifications" are enabled you can open a dropdown by clicking on "Realtime Configuration". The "Test Webhook" button will perform ownership verification (see below) and send a test POST request to the endpoint. Click save if your configuration is complete and new feed updates will be send to the endpoint in realtime.

To ensure that you are the owner of the endpoint you configure, we perform a verification step on saving a new endpoint. There are two verification methods available: verification via DNS and verfication via HTTP. You need to pass one of these two verifications in order to setup the webhook.

Verification via DNS

Configure a TXT record _getstream for the domain of the webhook with value getstream=your_app_api_key. For example if your webhook endpoint is https://example.com/feeds/ you will need to create a TXT record _getstream.example.com with value getstream=your_app_api_key.

Verification via HTTP request

To validate using a GET request, make sure the webhook returns your most recent API Key on a GET request. Make sure that the response body is in plain text (no markup, whitespaces, ...).

Example data

Please find below an example of the data your webhook will receive:

    
      [
        {
          "deleted":[],
          "new":[{"actor":"1","verb":"tweet","object":"1","target":null,"time":"2014-12-15T17:20:37.258","foreign_id":null,"id":"af781804-847e-11e4-8080-80012fb97b9e","tweet":"Hello world"}],
          "published_at":"2014-12-15T17:20:37.263518+00:00",
          "feed":"user:2",
          "app_id": "123"
        },
        {
          "deleted":["38f81366-847f-11e4-9c94-0cc47a024be0"],
          "new":[],
          "published_at":"2014-12-15T17:20:37.263518+00:00",
          "feed":"timeline:1",
          "app_id": "123"
        }
      ]
    
  

Stream allows you to configure your own ranking method. You can add multiple ranking methods to a given feed group.

An example ranking config is shown below:

{
    "score": "decay_linear(time) * popularity ^ 0.5",
     "defaults": {
        "popularity": 1
    }
}

Available Functions

Adding Activities

Below is an example of how to add activities with custom ranking:

# 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 - adding your ranking method as a parameter (in this case, "popularity"):
activity_data = { :actor => "User:2", :verb => "pin", :object => "Place:42", :target => "Board:1", :popularity => 5 }

activity_response = user_feed_1.add_activity(activity_data)

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

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

// Add an activity to the feed - adding your ranking method as a parameter (in this case, "popularity"):
var activity = { "actor": "User:2", "verb": "pin", "object": "Place:42", "target": "Board:1", "popularity": 5 };

// Add Activity - Returns promise:
user1.addActivity(activity)
    .then(onSuccess)
    .catch(onFailure);

# 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 - adding your ranking method as a parameter (in this case, "popularity"):
activity_data = { "actor": "User:2", "verb": "pin", "object": "Place:42", "target": "Board:1", "popularity": 5 }


activity_response = user_feed_1.add_activity(activity_data)

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

// Add an activity to the feed, where actor, object and target are references to objects  - and adding your ranking method as a parameter (in this case, "popularity"):
$data = [
    "actor" =>"User:2",
    "verb" =>"pin",
    "object" =>"Place:42",
    "target" =>"Board:1",
    "popularity" => 5,
];

$userFeed1->addActivity($data);

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

// Add an activity to the feed, where actor, object and target are references to objects - adding your ranking method as a parameter (in this case, "popularity"):
activity := stream.Activity{
    Actor:  "User:1",
    Verb:   "pin",
    Object: "Place:42",
    Target: "Board:1",
    Extra: map[string]interface{}{
        "popularity": 5,
    },
}
_, err := userFeed.AddActivity(activity)
if err != nil {
    panic(err)
}

// 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 - adding your ranking method as a parameter (in this case, "popularity"):
var activity = new Activity("User:2", "pin", "Place:42")
{
    Target = "Board:1"
};
activity.SetData("popularity", 5);

var activityResponse = await userFeed1.AddActivity(activity);

Retrieving Activities

Below is an example of how to retrieve activities sorted by custom ranking:

# Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
result = user_feed_1.get(:limit=>5, :ranking=>'activity_popularity')

/*
 * Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
 */
user1.get({ limit:20, ranking:'activity_popularity'})
  .then(activitiesSuccess)
  .catch(activitiesError);

# Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
result = user_feed_1.get(limit=5, ranking="activity_popularity")

// Get 5 activities - using limit, offset - and sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled):
$options = ['ranking' => 'activity_popularity'];

$results = $userFeed1->getActivities(0, 5, $options);

// Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
resp, err := userFeed.GetActivitiesWithRanking("activity_popularity", stream.WithActivitiesLimit(5))
if err != nil {
    panic(err)
}
for _, activity := range resp.Results {
    // ...
}

// Get activities sorted by the ranking method labelled 'activity_popularity' (Ranked Feeds Enabled)
var result = await userFeed1.GetFlatActivities(GetOptions.Default.WithLimit(5).WithRanking("activity_popularity"));

Configuring ranking can be complex. Feel free to reach out to support if you have questions.

Stream supports a Linear, Exponential, and Gauss decay. For each decay function, we support 4 arguments: Origin, Scale, Offset, and Decay. You can pass either a timedelta string (such as 3d, 4w), or a numeric value.

The example below defines a simple_gauss with the following params:

• scale: 5 days
• offset: 1 day
• decay: 0.3 day

This means that an activity younger than 1 day (the offset) will return a score of 1. An activity which is exactly 6 days old (offset + scale) will get a score of 0.3 (the decay factor). The full JSON config is shown below:

{
  "functions":{
    "simple_gauss":{
      "base":"decay_gauss",
      "scale":"5d",
      "offset":"1d",
      "decay":"0.3"
    },
    "popularity_gauss":{
      "base":"decay_gauss",
      "scale":"100",
      "offset":"5",
      "decay":"0.5"
    }
  },
  "defaults": {
      "popularity": 1
  },
  "score":"simple_gauss(time)*popularity"
}

You can specify defaults for the variables you use. The example above sets popularity to 1 if it's missing from the activity. We highly recommend setting up defaults to prevent errors when retrieving activities without these variables.

Configuring ranking can be complex. Feel free to reach out to support if you have questions!

Personalization

Stream makes it easy to add personalized feeds to your application. You can setup personalized feeds by implementing our analytics platform and reaching out to our data science and sales team.

As your users interact with your application, Stream starts to understand what they are interested in. You can use these insights to do a whole lot of awesome:

• Personalize Feeds
• Create Follow Suggestions
• Optimize Emails
• Product Recommendations
• Content Recommendations

This is our most advanced feed technology to date. It enables you to substantially improve the engagement, conversion and retention within your app.

Learn more about Personalization.

Analytics

The Stream Analytics platform helps you understand how your users are engaging with your feed.

Quickly glean insights on:

• Feed Quality
• Users & Interests
• Content Producers

Analytics provides specialized reporting that goes far beyond pageviews - feed-specific insights you won't get from GA or Mixpanel.

Learn more about Analytics.

In-Depth Documentation

Stream's Follow Many functionality gives you a fast method to follow many feeds in one go. This is convenient when importing data or on-boarding new users.

Follow Many has is a limit of 2,500 follows per request.

# Batch following many feeds
# Let timeline:1 will follow user:1, user:2 and user:3
follows = [
    {:source => 'timeline:1', :target => 'user:1'},
    {:source => 'timeline:1', :target => 'user:2'},
    {:source => 'timeline:1', :target => 'user:3'}
]
client.follow_many(follows)

// Batch following many feeds
// Let timeline:1 will follow user:1, user:2 and user:3
var follows = [
  {'source': 'timeline:1', 'target': 'user:1'},
  {'source': 'timeline:1', 'target': 'user:2'},
  {'source': 'timeline:1', 'target': 'user:3'}
];

client.followMany(follows);

# Batch following many feeds
# Let timeline:1 will follow user:1, user:2 and user:3
follows = [
    {'source': 'timeline:1', 'target': 'user:1'},
    {'source': 'timeline:1', 'target': 'user:2'},
    {'source': 'timeline:1', 'target': 'user:3'}
]
client.follow_many(follows)
# copy only the last 10 activities from every feed
client.follow_many(follows, activity_copy_limit=10)

// Batch following many feeds
// Let timeline:1 will follow user:1, user:2 and user:3
$follows = [
    ['source' => 'timeline:1', 'target' => 'user:1'],
    ['source' => 'timeline:1', 'target' => 'user:2'],
    ['source' => 'timeline:1', 'target' => 'user:3'],
];

$batcher->followMany($follows);

/* Batch following many feeds */
FollowMany followMany = new FollowMany.Builder()
    .add("user:1", "user:2")
    .add("user:1", "user:3")
    .add("user:1", "user:4")
    .add("user:2", "user:3")
    .build();
feed.followMany(followMany);

// Batch following many feeds
// Let timeline:1 will follow user:1, user:2 and user:3
follows := []stream.FollowRelationship{
    stream.NewFollowRelationship(timelineFeed, userFeed1),
    stream.NewFollowRelationship(timelineFeed, userFeed2),
    stream.NewFollowRelationship(timelineFeed, userFeed3),
}
err = client.FollowMany(follows)
if err != nil {
    panic(err)
}
// copy only the last 10 activities from every feed
err = client.FollowMany(follows, stream.WithFollowManyActivityCopyLimit(10))
if err != nil {
    panic(err)
}

// Batch following many feeds
// Let timeline:1 follow user:1, user:2 and user:3
var follows = new[]
{
    new Follow("timeline:1", "user:1"),
    new Follow("timeline:1", "user:2"),
    new Follow("timeline:1", "user:3")
};
await client.Batch.FollowMany(follows);

// copy only the last 10 activities from every feed
await client.Batch.FollowMany(follows, 10);

Parameters

Note: The API does not return any data.

Multiple activities can be added with a single batch operation. This is very convenient when importing data to Stream.

Take a look at the example below:

activities = [
    {:actor => 'User:1', :verb => 'tweet', :object => 'Tweet:1'},
    {:actor => 'User:2', :verb => 'watch', :object => 'Movie:1'}
]
user_feed_1.add_activities(activities)

var activities = [
    {'actor': 'User:1', 'verb': 'tweet', 'object': 'Tweet:1'},
    {'actor': 'User:2', 'verb': 'watch', 'object': 'Movie:1'}
];

user1.addActivities(activities)
    .then(function(data) { /* on success */ })
    .catch(function(reason){ /* on failure */ });

activities = [
    {'actor': 'User:1', 'verb': 'tweet', 'object': 'Tweet:1'},
    {'actor': 'User:2', 'verb': 'watch', 'object': 'Movie:1'}
]
user_feed_1.add_activities(activities)

$activities = [
    ['actor' => 'User:1', 'verb' => 'tweet', 'object' => 'Tweet:1'],
    ['actor' => 'User:2', 'verb' => 'watch', 'object' => 'Movie:1'],
];

$userFeed1->addActivities($activities);

FlatActivityServiceImpl<SimpleActivity> flatActivityService = feed.newFlatActivityService(SimpleActivity.class);

/* activity 1 */
SimpleActivity activity = new SimpleActivity();
activity.setActor("actor");
activity.setObject("object");
activity.setTarget("target");
activity.setVerb("verb");
activity.setForeignId("foreign1");

/* activity 2 */
SimpleActivity activity2 = new SimpleActivity();
activity2.setActor("actor");
activity2.setObject("object");
activity2.setTarget("target");
activity2.setVerb("verb");
activity2.setForeignId("foreign2");

List<SimpleActivity> listToAdd = new ArrayList<>();
listToAdd.add(activity);
listToAdd.add(activity2);

StreamActivitiesResponse<SimpleActivity> streamResponse = flatActivityService.addActivities(listToAdd);

activities := []stream.Activity{
    {Actor: "User:1", Verb: "tweet", Object: "Tweet:1"},
    {Actor: "User:2", Verb: "watch", Object: "Movie:1"},
}
_, err := userFeed.AddActivities(activities...)
if err != nil {
    panic(err)
}

var activities = new Activity[]{
    new Activity("User:1", "tweet", "Tweet:1"),
    new Activity("User:2", "watch", "Movie:1")
};

await userFeed1.AddActivities(activities);

Parameters

Activity IDs

The API will return a response with a list containing the activity ids.

Parameters

It is possible to discard activities added to a feed based on certain rules.

Common Use Case

One common use case is when users post in a feed that one of their own notification feeds follow.

By default, the user gets a notification of their own activity. By applying a discard rule, the user's own activities can be filtered.

Parameters

The following discard rules are available:

To enable this feature, contact support with:

• the name of the feed group
• the name of the rule to apply

Every Application is rate limited at the API endpoint. These limits are set on a 1-minute, 15-minute and 1-hour time windows, API requests have specific rate limits. For example, reading a feed has a different limit than establishing a follow relationship.

What Happens when you are Rate Limited

If an API call exceeds a rate limit during the target time window, subsequent requests for the same API function will be rejected. The payload returned for that API call will indicate that rate limiting has occurred.

If your application becomes rate-limited it doesn't block other API calls from working. For example, hitting a rate limit on follows will still allow you to read feeds. Each 'resource' is rate-limited separately.

Rate limits are reset at the end of each time window.

How to avoid rejected API requests

For Pro and Enterprise plans, Stream will review your feed group architecture, and set higher rate limits for your production application. For other paid plans, you will need to review responses from Stream to watch for error conditions indicating that your API request was rate-limited and retry. We recommend implementing an exponential back-off retry mechanism.

Rate Limits

You can view the current API status on the Status page.

In general, expect your feed to load in about 60ms. The most common cause of slower performance is latency. You can improve this by selecting a data center close to you.

Stream is currently available on different locations. When you create an application, you should select the region that is closes to you to get the best latency:

• US East - Virginia: us-east
• Europe West - Ireland: dublin
• Asia - Singapore: singapore
• Asia - Tokyo: tokyo

Make sure you provide your application region when intializing the client:

client = Stream::Client.new('YOUR_API_KEY','API_KEY_SECRET', 'SITE_ID', :location => 'us-east')

// connect to the us-east region
var client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET', 'SITE_ID', {'location': 'us-east'});

# connect to the us-east region
import stream
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET', location='us-east')

$client = new GetStream\Stream\Client('YOUR_API_KEY', 'API_KEY_SECRET');
$client->setLocation('us-east');

ClientConfiguration streamConfig = new ClientConfiguration().setRegion(StreamRegion.US_EAST);
StreamClient streamClient = new StreamClientImpl(streamConfig, "API_KEY", "API_SECRET");

// connect to the us-east region
client, err := stream.NewClient(
    // API key
    "YOUR_API_KEY",
    // API secret
    "API_KEY_SECRET",
    // API region
    stream.WithAPIRegion("us-east"),
)
if err != nil {
    panic(err)
}

var opts = StreamClientOptions.Default;
opts.Location = StreamApiLocation.USEast;
var client = new StreamClient("YOUR_API_KEY", "API_KEY_SECRET", opts);

Enrichment & Slow Performance

Another common cause of slow feed performance is the enrichment step. Often you'll send references to your database in the activities. When loading your feed you need to run certain database queries to load the latest version of this data.

In cases like this there are 2 things to keep in mind:

1. Batch all the database queries. Never run N queries for N items in the feed.
2. Cache the lookup by primary key using a model layer cache (recommended only for large apps).

Our framework/ORM integrations can also handle enrichment for your automatically. Have a look at our enrichment documentation.

Postman is a popular tool for developing and testing RESTful web-services and APIs.

While we recommend developing for the Stream API via an API Client in your language of choice, it is also often helpful to review and run the low-level HTTP requests that are associated with our APIs. Postman is a great tool for achieving this.

Get started or log in to download the Postman Collection.

Using the Collection

1. Import the Collection into Postman.
2. Browse the Collection folders and select a request to send. Review the request 'params' area and 'body' tab for request specific query string parameters or payload data.
3. Click the 'Send' button to initiate the request and check on the response panel to see the results.

Personalization is a powerful feature. It enables you to leverage machine learning to optimize what's shown in the feed. The 5 most common use cases are:

Famous examples of discovery feeds are Instagram's explore section and Pinterest's main feed. Edge rank is used by Facebook and Linkedin. Stream uses 3 data sources for personalization:

1. Feeds & Follows

The best way to understand how feeds and follows work is to try our 5 minute interactive tutorial. We also have extensive documentation which provides detailed information on the API.

2. Analytics

The purpose of analytics is to track which activities a user is looking at and what they are engaging with. Basically, you want to track everything that indicates a user's interest in something. Common examples include:

• Clicking on a link
• Likes or comments
• Sharing an activity
• Viewing another user's profile page
• Search terms

The events and data you want to track is often different than what you traditionally track in Google Analytics or Mixpanel. Stream's analytics is designed to run side by side your existing analytics solution.

3. Collections

Collections enable you to sync information to Stream that's not captured by analytics or feeds. Common examples include user profiles and product information.

This tutorial will explain how to build Instagram style personalization using Stream. The underlying tech is similar to that of a Pinterest style feed, Etsy’s e-commerce recommendations, email digests (such as Quora) or YouTube’s content suggestions.

The goal of this tutorial is to build a feed similar to Instagram's 'Explore' feed. The content is based on what type of images you've engaged with in the past as well as graph analysis. For example, if you often click on snowboarding pictures it will learn that you like snowboarding and display related posts.

Step 1: Test Data

Let's get started. As a first step we'll want to insert test data.

• Ruby
• JS/Node
• Python
• PHP
• Go

# Step 1: Setup the test data
require 'stream'
require 'httparty'

client = Stream::Client.new('YOUR_API_KEY', 'API_KEY_SECRET')
activities = JSON.parse(HTTParty.get('http://bit.ly/test-activities-gist'))
client.feed('user',  'global').add_activities(activities)

// Step 1: Setup the test data
let stream = require('getstream');
let request = require('request');

var API_KEY = process.env.STREAM_API_KEY
  , API_SECRET = process.env.STREAM_API_SECRET;

if (! API_KEY || ! API_SECRET) {
    throw new Error('Expected STREAM_API_KEY, STREAM_API_SECRET env vars');
}

let client = stream.connect(API_KEY, API_SECRET);

// 1. Setup the test data
request.get(
  'http://bit.ly/test-activities-gist',
  (error, response, body) => {
    if (error) {
      console.log(error);
    }
    else {
      let activities = JSON.parse(body);
      client.feed('user', 'global').addActivities(activities);
    }
});

# Step 1: Setup the test data
import stream
import requests
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET')

activities = requests.get('http://bit.ly/test-activities-gist').json()
for activity in activities:
    activity_response = client.feed('user', 'global').add_activity(activity)
    print(activity_response)

// Step 1: Setup the test data
$client = new GetStream\Stream\Client('YOUR_API_KEY', 'API_KEY_SECRET');

$content = file_get_contents('http://bit.ly/test-activities-gist');
$activities = json_decode($content, true);

$response = $client->feed('user', 'global')->addActivities($activities);
echo json_encode($response) . "\n";

// 1. Setup the test data
import stream "gopkg.in/GetStream/stream-go2.v1"

client, err := stream.NewClient("YOUR_API_KEY", "API_KEY_SECRET")
if err != nil {
    panic(err)
}

resp, err := http.Get("http://bit.ly/test-activities-gist")
if err != nil {
    panic(err)
}
content, err := ioutil.ReadAll(resp.Body)
if err != nil {
    panic(err)
}
defer resp.Body.Close()
var activities []stream.Activity
err = json.Unmarshal(content, &activities)
if err != nil {
    panic(err)
}
_, err = client.FlatFeed("user", "global").AddActivities(activities...)
if err != nil {
    panic(err)
}

If you run the above snippet you'll insert 3 activities with the following images and tags:

#tree #snow #winter #landscape

#beach #van #surfing #travel

#dog #puppy #running #labrador

Step 2: Analytics

For this tutorial we'll only track clicks. If you're building a production application you'll want to track any type of event that signals a user's interest. The example below shows how to perform the analytics tracking if a user clicks on the 2nd image. Analytics tracking is normally done client-side, in this case we are using the JS analytics client.

• JS/Node

// set the current user
client.setUser({id: 123, alias: 'john'});
// track a click on the 2nd picture
var engagement = {
  // the label for the engagement, ie click, retweet etc.
  'label': 'click',
  // the ID of the content that the user clicked
  'content': {
    'foreign_id': 'picture:2'
  },
  // score between 0 and 100 indicating the importance of this event 
  // IE. a like is typically a more significant indicator than a click
  'score': 15,
  // (optional) the position in a list of activities
  'position': 2
};

client.trackEngagement(engagement);

The example above uses a score of 15. The score is a number between 0 and 100 and indicates the importance of an event. A click is typically less important than a like or a share, so give those events a higher score.

Step 3: Understanding Features

Those clicks give us a hint that the user is interested in that activity. There are many features attached to a given activity. For this example, we'll take a look at the features attached to the 2nd activity:

• Ruby
• JS/Node
• Python
• PHP
• Go

# Analyze which features activity with foreign id picture:2 has
features = client.personalization.get('analyze_features', foreign_id: 'picture:2')
puts features

// Analyze which features activity with foreign ID picture:2 has
let params = {foreign_id: 'picture:2'};
client.personalization.get('analyze_features', params).then(
  (resolution) => console.log(resolution["response"]["data"]),
  (rejection) => console.log(rejection)
);

# Analyze which features activity with foreign id picture:2 has
features = client.personalization.get('analyze_features', foreign_id='picture:2')
print(features)

// Analyze which features activity with foreign id picture:2 has
$features = $client->personalization()->get('analyze_features', ['foreign_id' => 'picture:2']);

print_r($features);

// Analyze which features activity with foreign id picture:2 has
featuresResp, err := client.Personalization().Get("analyze_features", map[string]interface{}{"foreign_id": "picture:2"})
if err != nil {
	// ...
}

Once you've ran the code, ask yourself why the user is interested in this picture. Is it because the picture is about surfing? Maybe it indicates that he/she likes the post since it's created by a friend? One click doesn't give us significant data, but as the user keeps returning to your app, an interest profile starts to form.

Step 4: Follows

Personalization works best if you combine explicit follow relationships with analytics events. The example below shows how to create a follow relationship.

• Ruby
• JS/Node
• Python
• PHP
• Go

# John follows user conner3400
client.feed('timeline', 'john').follow('user', 'conner3400')

// John follows user conner3400
john = client.feed('timeline', 'john');
john.follow('user', 'conner3400');

# John follows user conner3400
client.feed('timeline', 'john').follow('user', 'conner3400')

// John follows user conner3400
$client->feed('timeline', 'john')->follow('user', 'conner3400');

// John follows user conner3400
john := client.FlatFeed("timeline", "john")
conner := client.FlatFeed("user", "conner3400")
err = john.Follow(conner)
if err != nil {
	panic(err)
}

Step 5: Reading the Personalized Feed

With both follows and analytics in place we now have the ability to read the personalized feed.

• Ruby
• JS/Node
• Python
• PHP
• Go

activities = client.personalization.get('personalized_feed', feed_slug: 'timeline', user_id: 'john')
puts activities

params = {
  user_id: 'john',
  feed_slug: 'timeline'
};
client.personalization.get('personalized_feed', params).then(
  (resolution) => console.log(resolution["response"]["data"]),
  (rejection) => console.log(rejection)
);

activities = client.personalization.get('personalized_feed', feed_slug='timeline', user_id='john')
print(activities)

$activities = $client->personalization()->get('personalized_feed', ['feed_slug' => 'timeline', 'user_id' => 'john']);

print_r($activities);

resp, err = client.Personalization().Get("personalized_feed", map[string]interface{}{
	"feed_slug": "timeline",
	"user_id":   "john",
})
if err != nil {
	// ...
}

Step 6: Follow Suggestions

With the follow relationships in place, we have enough data to create follow suggestions.

• Ruby
• JS/Node
• Python
• PHP
• Go

suggestions = client.personalization.get('follow_recommendations', user_id: 'john', target_feed_slug: 'user', source_feed_slug: 'timeline')
puts suggestions

params = {
  user_id: 'john',
  source_feed_slug: 'timeline',
  target_feed_slug: 'user'
};
client.personalization.get('follow_recommendations', params).then(
  (resolution) => console.log(resolution["response"]["data"]),
  (rejection) => console.log(rejection)
);

suggestions = client.personalization.get('follow_recommendations', target_feed_slug='user', user_id='john', source_feed_slug='timeline')
print(suggestions)

$suggestions = $client->personalization()->get('follow_recommendations', [
    'user_id' => 'john',
    'source_feed_slug' => 'timeline',
    'target_feed_slug' => 'user',
]);

print_r($suggestions);

resp, err = client.Personalization().Get("follow_recommendations", map[string]interface{}{
	"user_id":          "john",
	"source_feed_slug": "timeline",
	"target_feed_slug": "user",
})
if err != nil {
	// ...
}

This tutorial explained a simplified version of personalization for your app. Note: these algorithms need to be customized for each enterprise customer. Contact our data science team to learn how personalization can enhance your app.

Personalization is custom for every enterprise customer of Stream. The SDK exposes a flexible GET method to enable you to easily make authenticated get requests to personalization:

• Ruby
• JS/Node
• Python
• PHP
• Go

# Read the personalization feed for a given user
client.personalization.get('personalized_feed', user_id: 123, feed_slug: 'timeline')

# Our data science team will typically tell you which endpoint to use
client.personalization.get('discovery_feed', user_id: 123, source_feed_slug: 'timeline', target_feed_slug: 'user')

# Read the personalized feed for a given user
params = {user_id: '123', feed_slug: 'timeline'};
client.personalization.get('personalized_feed', params).then(
  (resolution) => console.log(resolution["response"]["data"]),
  (rejection) => console.log(rejection)
);

# Our data science team will typically tell you which endpoint to use
params = {user_id: '123', source_feed_slug: 'timeline', target_feed_slug: 'user'}
client.personalization.get('discovery_feed', params).then(
  (resolution) => console.log(resolution["response"]["data"]),
  (rejection) => console.log(rejection)
);

# Read the personalized feed for a given user
client.personalization.get('personalized_feed', user_id=123, feed_slug='timeline')

# Our data science team will typically tell you which endpoint to use
client.personalization.get('discovery_feed', user_id=123, source_feed_slug='timeline', target_feed_slug='user')

// Read the personalized feed for a given user
$client->personalization()->get('personalized_feed', [
    'user_id' => 123,
    'feed_slug' => 'timeline',
]);

// Our data science team will typically tell you which endpoint to use
$client->personalization->get('discovery_feed', [
    'user_id' => 123,
    'source_feed_slug' => 'timeline',
    'target_feed_slug' => 'user',
]);

// Read the personalization feed for a given user
resp, err := client.Personalization().Get("personalized_feed", map[string]interface{}{
	"user_id":   123,
	"feed_slug": "timeline",
})
if err != nil {
	// ...
}

// Our data science team will typically tell you which endpoint to use
resp, err = client.Personalization().Get("discovery_feed", map[string]interface{}{
	"user_id":          123,
	"source_feed_slug": "timeline",
	"target_feed_slug": "user",
})
if err != nil {
	// ...
}

Stream makes it easy to add follow suggestions to your app. Simply make the API call shown below to retrieve a list of follow suggestions.

suggestions = client.personalization.get('follow_recommendations', target_feed_slug='user', user_id='123', source_feed_slug='timeline')
print(suggestions)

Follow suggestions are disabled by default. Contact support so we can enable it for your organization.

By default the follow suggestions are based on a standardized graph analysis algorithm. Our data science team can work with you to create a customized algorithm for your app. Contact sales@getstream.io to learn more.

We recommend tracking every event for each user, which allows you to gain a better understanding of that user's interests. Common examples include:

• Clicking on a link
• Likes or comments
• Sharing an activity
• Viewing another user's profile page
• Searching for a certain user/content/topic/etc.

Stream Analytics supports tracking events via JS, iOS, Android or email redirects:

• JavaScript Client
• iOS Client
• Android Client
• Email Redirects

You're currently not logged in. Login so we can add your API key in the documentation snippets.

The code below shows how to install Stream's Analytics SDK:

• JS/Node
• iOS
• Android

// Add this async loader code anywhere in your HTML code

<script type="text/javascript">
!function(t,e){t("StreamAnalytics","https://d2j1fszo1axgmp.cloudfront.net/2.7.0/stream-analytics.min.js",e)}(function(t,e,n){var s,i,r;n["_"+t]={},n[t]=function(e){n["_"+t].clients=n["_"+t].clients||{},n["_"+t].clients[e.apiKey]=this,this._config=e};var c=function(t){return function(){return this["_"+t]=this["_"+t]||[],this["_"+t].push(arguments),this}};s=["setUser","trackImpression","trackEngagement"];for(var a=0;a<s.length;a++){var o=s[a];n[t].prototype[o]=c(o)}i=document.createElement("script"),i.async=!0,i.src=e,r=document.getElementsByTagName("script")[0],r.parentNode.insertBefore(i,r)},this);
</script>

// the client is available via CocoaPods, just add this to you Podfile

pod 'stream-analytics-ios'

// download the latest release from here: https://github.com/GetStream/stream-analytics-android/releases/

• JS/Node
• iOS
• Android

var client = new StreamAnalytics({
  apiKey: "YOUR_API_KEY",
  token: "ANALYTICS_TOKEN"
});

// Initialize StreamAnalytics in AppDelegate

#import "AppDelegate.h"
#import "Stream.h"

@interface AppDelegate ()
@end

@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    //enable debug logging
    [StreamAnalytics enableLogging:YES];
    return YES;
}
@end

// Import the library in your Gradle project:

dependencies {
  compile files('/path_to_file/stream-analytics-release-1.1.0.aar')
}

// Initialize the StreamAnalytics client
StreamAnalyticsAuth auth = new StreamAnalyticsAuth("YOUR_API_KEY","ANALYTICS_TOKEN");
StreamAnalytics client = StreamAnalyticsImpl.getInstance(auth);

      <dict>
      <key>APIKey</key>
      <string></string>
      <key>JWTToken</key>
      <string></string>
      </dict>
    

        <uses-permission android:name="android.permission.INTERNET" />
      

Always specify the current user before sending events:

• JS/Node
• iOS
• Android

// user id and a friendly alias for easier to read reports
client.setUser({id: 486892, alias: 'Julian'});

#import "Stream.h"


// set user id only 
[[StreamAnalytics sharedInstance] setUserId:@"486892"];

// add friendly alias for the user
[[StreamAnalytics sharedInstance] setUserId:@"486892" andAlias:@"Julian"];

// set user data
client.setUser("486892", "Eric");

// you can also set the userId only
// client.setUserId("486892");

The snippet below shows an example of how to track engagements. Emgagement examples include likes, comments, profile views and link clicks.

• JS/Node
• iOS
• Android

var engagement = {
  // the label for the engagement, ie click, retweet etc.
  'label': 'click',
  // the ID of the content that the user clicked
  'content': {
    'foreign_id': 'tweet:34349698'
  },
  // score between 0 and 100 indicating the importance of this event 
  // IE. a like is typically a more significant indicator than a click
  'score': 2,
  // (optional) the position in a list of activities
  'position': 3,
  // (optional) the feed the user is looking at
  'feed_id': 'user:thierry',
  // (optional) the location in your app. ie email, profile page etc
  'location': 'profile_page'
};

client.trackEngagement(engagement);

StreamEngagement *event = [StreamEngagement createEngagementEvent:@"click" withContent: @{@"foreign_id":@"message:34349698"}.mutableCopy]];

event.position = @"3";
event.boost = @2;
event.feedId = @"user:thierry";
event.location = @"profile_page";

[[StreamAnalytics sharedInstance] send:event];

client.send(new Engagement.EventBuilder()
    .withFeedId("user:thierry")
    .withContent(
        new Content.ContentBuilder()
            .withForeignId("message:34349698")
            .withAttribute("verb", "share")
            .withAttribute("actor", new ContentAttribute("1", "user1"))
            .build()
        )
    .withBoost(2)
    .withLocation("profile_page")
    .withPosition("3")                
    .build()
);

Parameters

Tracking impressions allows you to learn what specific users are not interested in. If the app often shows posts about football, and the user never engages with those posts, we can conclude that we're displaying the wrong content. The code below shows how to track that a user viewed 3 specific activities:

• JS/Node
• iOS
• Android

var impression = {
  // the list of content IDs displayed to the user
  'content_list': ['tweet:34349698', 'tweet:34349699', 'tweet:34349697'],
  // (optional) the feed where this content is coming from
  'feed_id': 'flat:tommaso',
  // (optional) the location in your app. ie email, profile page etc
  'location': 'profile_page'
};

// send the impression events
client.trackImpression(impression);

//track an impression
StreamImpression *event = [StreamImpression createImpressionEventWithContentList:@[@"song:34349698", @"song:34349699", @"song:34349697"]];

// (optional) the feed where this content is coming from
event.feedId = @"flat:tommaso";
// (optional) the location in your app. ie email, profile page etc
event.location = @"ios-app";

// send the impression events
[[StreamAnalytics sharedInstance] send:event];

client.send(new Impression.EventBuilder()
    .withContentList(
        new Content.ContentBuilder()
            .withForeignId("tweet:34349698")
            .withAttribute("verb", "share")
            .withAttribute("actor", new ContentAttribute("1", "user1"))
            .build(),
        new Content.ContentBuilder()
            .withForeignId("tweet:34349699")
            .build(),
        new Content.ContentBuilder()
            .withForeignId("tweet:34349610")
            .build()
    )
    .withFeedId("flat:tommaso")
    .withLocation("android-app")
    .build()
);

Be sure to use the same foreign ids as used in your feeds. This allows Stream to understand the content of the activities.

Parameters

Users tend to engage with emails, even when they aren't engaged with your app. Thus, it's important to track how they interact with your emails.

Tracking clicks in emails works via redirects. You can use our client libraries to generate a redirect link.

Example

• JS/Node
• Python
• PHP
• Go

// the url to redirect to
let target_url = 'http://mysite.com/detail';

// track the impressions and a click
let impression = {
    content_list: ['tweet:1', 'tweet:2', 'tweet:3'], 
    user_data: 'tommaso', 
    location: 'email',
    feed_id: 'user:global'
};

let engagement = {
    content: 'tweet:2', 
    label: 'click',
    position: 1, 
    user_data: 'tommaso', 
    location: 'email',
    feed_id: 'user:global'
};

let events = [impression, engagement];
let tracking_url = client.client.createRedirectUrl(target_url, "tommaso", events);

// when the user opens the tracking url in their browser gets redirected to the target url the events are added to our analytics platform

# the url to redirect to
target_url = 'http://mysite.com/detail'

# track the impressions and a click
impression = {
    'content_list': ['tweet:1', 'tweet:2', 'tweet:3'], 
    'user_data': 'tommaso', 
    'location': 'email',
    'feed_id': 'user:global'
}

engagement = {
    'content': 'tweet:2', 
    'label': 'click',
    'position': 1, 
    'user_data': 'tommaso', 
    'location': 'email',
    'feed_id': 
    'user:global'
}

events = [impression, engagement]
tracking_url = client.create_redirect_url(target_url, user_id, events)

# when the user opens the tracking url in their browser gets redirected to the target url
# the events are added to our analytics platform

$client = new GetStream\Stream\Client('YOUR_API_KEY', 'API_KEY_SECRET');

// the url to redirect to
$targetUrl = 'http://my.application.com/page/';

$impression = [
  'content_list' => ['tweet:34349698', 'tweet:34349699', 'tweet:34349697'],
  'feed_id' => 'flat:tommaso',
  'location' => 'profile_page',
  'user_data' => ['id' => 'bubbles'],
  'label' => 'impression',
];

$engagement = [
    'content' => 'tweet:34349698',
    'feed_id' => 'flat:tommaso',
    'location' => 'profile_page',
    'user_data' => ['id' => 'frank'],
    'label' => 'click',
];

$events = [$impression, $engagement];
$trackingUrl = $client->createRedirectUrl($targetUrl, $events);

// when the user opens the tracking url in their browser gets redirected to the target url
// the events are added to our analytics platform

// the URL to direct to
targetURL := "http://mysite.com/detail"

// track the impressions and a click
impression := ImpressionEventsData{}.
	WithForeignIDs("tweet:1", "tweet:2", "tweet:3").
	WithUserData(NewUserData().String("tommaso")).
	WithLocation("email").
	WithFeedID("user:global")

engagement := EngagementEvent{}.
	WithForeignID("tweet:2").
	WithLabel("click").
	WithPosition(1).
	WithUserData(NewUserData().String("tommaso")).
	WithLocation("email").
	WithFeedID("user:global")

trackingURL, err := client.Analytics().RedirectAndTrack(targetURL, impression, engagement)
if err != nil {
	panic(err)
}
// when the user opens the tracking URL in their browser gets redirected to the target URL
// the events are added to our analytics platform

In the code above, when a user clicks the tracking URL, they are re-directed to the specified target URL. During the re-direct, Stream tracks the impressions and engagement events you specified.

Collections enable you to sync information to Stream that is not captured by analytics or feeds. Examples include user profiles and product information. To sync this data, use the following 3 endpoints:

• Upsert
• Delete
• Select

The example below shows how to update or insert a user profile via the upsert command. You can update a max of 1000 items at once. If you need to update more than 1000 items you'll need to make multiple requests.

• Ruby
• JS/Node
• Python
• PHP
• Go
• C#

# Update the information for user with ID 123
client.collections.upsert('user', [{id: '123', name: 'johndoe', favorite_color: 'blue'}])

client.collections.upsert('user', [
    {id: '123', name: 'johndoe', favorite_color: 'blue'}
]).then(
  (resolution) => {
    console.log(resolution);
  ),
  (rejection) => {
    console.log(rejection);
  }
});

# Update the information for user with id 123
client.collections.upsert('user', [{'id': '123', 'username': 'johndoe', 'favorite_color': 'blue'}])

// Update the information for user with id 123
$client->collections()->upsert('user', [
    [
        'id' => '123',
        'username' => 'johndoe',
        'favorite_color' => 'blue',
    ]
]);

// Update the information for user with ID 123
object := stream.CollectionObject{
	ID:   "123",
	Data: map[string]interface{}{
		"name": "johndoe",
		"favorite_color": "blue",
	},
}
err = client.Collections().Upsert("user", object)
if err != nil {
	panic(err)
}

// Update the information for user with ID 123
var obj = new CollectionObject("123");
obj.SetData("name", "johndoe");
obj.SetData("favorite_color", "blue");
await client.Collections.Upsert("user", obj);

Verify Stream is storing the correct data by using the select endpoint. A similar syntax can be used for removing the data.

• Ruby
• JS/Node
• Python
• PHP
• Go
• C#

# Read the data for user 123
objects = client.collections.get('user', ['123'])

# Delete the record for user 123
client.collections.delete('user', ['123'])

// 1. select the record for user with ID 123
objects = client.collections.select('user', ['123']).then(
  (resolution) => {
    resolution["response"]["data"].forEach((obj) => console.log(obj));
    // 2. Delete the record for user with ID 123
    client.collections.delete('user', ['123']);
  },
  (rejection) => {
    console.log(rejection);
  }

# Read the data for user 123
user = client.collections.select('user', [123])
# Delete the record for user 123
response = client.collections.delete('user', [123])

// Read the data for user 123
$user = $client->collections()->select('user', [123]);

// Delete the record for user 123
$response = $client->collections()->delete('user', [123]);

// Read the data for user 123
objects, err := client.Collections().Get("user", "123")
if err != nil {
	panic(err)
}

// Delete the record for user 123
err = client.Collections().Delete("user", "123")
if err != nil {
	panic(err)
}

// Read the data for user 123
var user = await client.Collections.Select("user", "123");

// Delete the record for user 123
await client.Collections.Delete("user", "123");

Reactions are a special kind of data that can be used to capture user interaction with specific activities. Common examples of reactions are: likes, comments and upvotes. Reactions are automatically returned to feeds' activities at read time when reading feeds within a user session (see section below for more information and examples).

// user sessions are commonly used client-side (eg. web / react native)
// the userToken variable is created server-side (often as part of part of the sign-up / sign-in flow)
// var userToken = client.createUserSessionToken(userId);

userSession = client.createUserSession(userId, userToken);

Reactions are always related to activities; in order to add a reaction to an activity you need to provide its ID.

Listed below are the parameters for adding reactions.

Parameters

• JS/Node

// add a like reaction to the activity with id activityId
userSession.reactions.add("like", activityId);

// adds a comment reaction to the activity with id activityId
userSession.reactions.add("comment", activityId, {"data": {"text": "awesome post!"}});

Here's a complete example:

• JS/Node

// first let's read current user's timeline feed and pick one activity
let response = await userSession.feed('timeline').get();
let activity = response.activities[0];

// then let's add a like reaction to that activity
await userSession.reaction.add("like", activity.id);

Reactions can be removed by their ID

• JS/Node

userSession.delete(reactionId);

Reactions can be updated by providing activity ID and reaction ID parameters.

Changes to reactions are propagated to all notified feeds; if the target_feeds list is updated, notifications will be added and removed accordingly.

Parameters

• JS/Node

userSession.reactions.update(activityId, reactionId "comment", {"text": "love it!"});

When adding a reaction, you can use the target_feeds parameter to notify a list of users about the new reaction. When specified, all targeted feeds will receive an activity containing a reference to the reaction.

• JS/Node

// adds a comment reaction to the activity and notify Thierry's notification feed
userSession.reactions.add("comment", activityId, {
    "data": {"text": "@thierry great post!"},
    "targetFeeds": ["notification:thierry"],
});

When using reactions, it is possible to request enriched activities that include attached reactions by type and reaction counters.

Listed below are the parameters for retrieving reactions.

Parameters

• JS/Node

// read user's timeline and include most recent reactions to all activities and their total count
userSession.feed('timeline').get({
    withRecentReactions: true,
    withReactionCounts: true,
});

// read user's timeline and include most recent reactions to all activities and her own reactions
userSession.feed('timeline').get({
    withOwnReactions: true,
    withReactionCounts: true,
});

This API endpoint allows you to upload files and to process your images (eg. create image thumbnails).

// user sessions are commonly used client-side (eg. web / react native)
// the userToken variable is created server-side (often as part of part of the sign-up / sign-in flow)
// var userToken = client.createUserSessionToken(userId);

userSession = client.createUserSession(userId, userToken);

Image and Files have separate API endpoints (eg. images can be resized, files cannot). Once the upload is completed the URL of the file/image is returned and is ready for use.

The returned URL is served via CDN and can be requested by anyone; in order to avoid resource enumeration attacks, a unique signature is added. Manipulating the returned URL will likely result in HTTP errors.

// uploading an image from the browser (input is a <input type="file"> form field)
userSession.images.upload(input.files[0]);

// uploading an image from React Native (imageURI is the URI of the file)
userSession.images.upload(imageURI);

// uploading a file from the browser (input is a <input type="file"> form field)
userSession.files.upload(input.files[0]);

// uploading a file from React Native (fileURI is the URI of the file)
userSession.files.upload(fileURI);

Files and images can be deleted using their URL.

// deleting an image using the url returned by the APIs
userSession.images.delete(imageURL);

// deleting a file using the url returned by the APIs
userSession.files.delete(fileURL);

Once an image is uploaded, it is possible to create variants of the same in different sizes.
The image to manipulate is selected using its URL. A new URL is then returned by the API.

Parameters

Resize

The resize parameter determines how the new image dimensions are applied. The default value for this parameter is "clip".

Allowed values:

• clip fits the image within the width and height boundaries without cropping or changing the aspect ratio.
• crop applies the new dimensions and keeps the aspect ratio by cropping the parts of the image outside of the new boundaries. You can use the crop parameter to control how the cropping is done.
• scale applies the new dimensions to the image. This method does not respect the aspect ratio and can create distorted images.
• fill same as "clip" but the resulting image will have the exact dimensions requested and filled with a solid background color.

Crop

When resizing the image with a crop, you can specify the cropping direction. By default images are copped started from their center. You combine directions in order to pick corners. Eg. "top,left" will use the top left corner as cropping position.

Allowed values: top, bottom, left, right, center

// create a 50x50 thumbnail and crop from center
userSession.images.process(imageURL, {h:50, w:50, resize:'crop'});

// create a 50x50 thumbnail using clipping (keeps aspect ratio)
userSession.images.process(imageURL, {h:50, w:50, resize:'clip'});

This endpoint allows you to retrieve open graph information from a URL which you can use to add images and a description to activities.

// user sessions are commonly used client-side (eg. web / react native)
// the userToken variable is created server-side (often as part of part of the sign-up / sign-in flow)
// var userToken = client.createUserSessionToken(userId);
userSession = client.createUserSession(userId, userToken);

userSession.og('http://www.imdb.com/title/tt0117500/');

Returns the following:

These tutorials get you up to speed quickly!

These example apps give you a quick overview of how to integrate Stream into your application.

• Cabin, React/Redux tutorial series
• Django Example Github
• Rails Example Github
• Laravel Example Github
• Node JS Example Github

This tutorial explains how to use Stream to build a scalable social network for music. In this example app you can follow your friends, artists and playlists. We're going to support the following features:

• Timeline/Newsfeed
• Hashtags
• @mentions
• Likes & comments
• Notification feed
• Realtime changes

Step 1: Setting up the feed groups

First of all we need to create feed groups for everything you can follow. For this app that will be "user", "artist" and "playlist". Next we'll need feeds to display the data. So we'll create the "timeline", "notification" and "tag" feeds groups. Take a moment to go to the dashboard and create these 6 feed groups. The "notification" feed group should be the "notification" feed type. The other 5 feed groups can be of the "flat" type.

Step 2: Follow users, artists and playlists

The example below shows you how to follow users, artists and playlists.

import stream

# Instantiate a new client
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET', 'APP_ID')
timeline_chris = client.feed('timeline', 'chris')

# Follow a friend
timeline_chris.follow('user', 'jack')
# Follow a playlist
timeline_chris.follow('playlist', '90s_hits')
# Follow an artist
timeline_chris.follow('artist', 'coldplay')

// Instantiate a new client
client, err := stream.NewClient(
    // API key
    "YOUR_API_KEY",
    // API secret
    "API_KEY_SECRET",
    // API region
    stream.WithAPIRegion("us-east"),
)
if err != nil {
    panic(err)
}

timelineChris := client.FlatFeed("timeline", "chris")
// follow a friend
userJack := client.FlatFeed("user", "jack")
err = timelineChris.Follow(userJack)
if err != nil {
    panic(err)
}
// follow a playlist
playlist90s := client.FlatFeed("timeline", "90s_hits")
err = timelineChris.Follow(playlist90s)
if err != nil {
    panic(err)
}
// follow an artist
artistColdplay := client.FlatFeed("artist", "coldplay")
err = timelineChris.Follow(artistColdplay)
if err != nil {
    panic(err)
}

// Instantiate a new client
var client = new StreamClient("YOUR_API_KEY", "API_KEY_SECRET");
var timelineChris = client.Feed("timeline", "chris");

// Follow a friend
await timelineChris.FollowFeed("user", "jack");
// Follow a playlist
await timelineChris.FollowFeed("playlist", "90s_hits");
// Follow an artist
await timelineChris.FollowFeed("artist", "coldplay");

Step 3: Posting an update

Let's dive straight into an example of how to add an activity:

jack = client.feed("user", "jack")

# Jack posts an update with a hashtag and @mention
jack.add_activity({
  "actor": "jack",
  "verb": "post",
  "object': "post:10",
  "foreign_id": "post:10",
  "to": ["notification:chris", "tag:amsterdam"],
  "message": "Hi @chris, the coldplay concert was totally amazing #amsterdam"
})

// Jack posts an update with a hashtag and @mention
_, err = userJack.AddActivity(stream.Activity{
    Actor:     "jack",
    Verb:      "post",
    Object:    "post:10",
    ForeignID: "post:10",
    To: []string{
        "notification:chris",
        "tag:amsterdam",
    },
    Extra: map[string]interface{}{
        "message": "Hi @chris, the coldplay concert was totally amazing #amsterdam",
    },
})
if err != nil {
    panic(err)
}

var jack = client.Feed("user", "jack");

// Jack posts an update with a hashtag and @mention
var activity = new Activity("jack", "post", "post:10")
{
    ForeignId = "post:10",
    To = new string[] { "notification:chris", "tag:amsterdam" }
};
activity.SetData("message", "Hi @chris, the coldplay concert was totally amazing #amsterdam");
await jack.AddActivity(activity);

First of all note how easy it is to add an activity. Certain fields like actor, verb and object are mandatory. Message is a custom field. You can add as many custom fields as you like. You can store numbers, strings, lists and even objects.

The TO field is comparable to how CC works for email. For a production app we recommnend storing the activity in your database, and syncing it to Stream.

Step 4: Likes & Comments

When a user likes an activity or writes a comment you'll want to:

• Notify the author of the original activity
• Show the like/comments to followers

The example below uses the TO support to write both to the user:chris and notification:jack feeds:

# Chris likes Jack's post
chris = client.feed("user", "chris")
chris.add_activity({
  "actor": "chris",
  "verb": "like",
  "object": "post:10",
  "foreign_id": "like:25",
  "to": ["notification:jack"]
})
# Notify Jack and show it to Chris' followers (via the "chris" user feed)

// Chris likes Jack's post
userChris := client.FlatFeed("user", "chris")
_, err = userChris.AddActivity(stream.Activity{
    Actor:     "chris",
    Verb:      "like",
    Object:    "post:10",
    ForeignID: "like:25",
    To: []string{
        "notification:jack",
    },
})
if err != nil {
    panic(err)
}
// Notify Jack and show it to Chris' followers (via the chris' user feed)

// Chris likes Jack's post
var chris = client.Feed("user", "chris");
var chrisActivity = new Activity("chris", "like", "post:10")
{
    ForeignId = "like:25",
    To = { "notification:jack" }
};
await chris.AddActivity(chrisActivity);

// Notify Jack and show it to Chris' followers (via the "chris" user feed)

Step 5: Reading a feed

It's easy to read a feed. You can use either offset or id_lt based pagination. For larger apps we recommend filtering using id_lt as it performs much better.

jack = client.feed('timeline', 'jack')

# Read the timeline for jack
activities = jack.get(limit=10)['results']
# Read the next page, use id filtering for optimal performance
next_activities = jack.get(limit=10, id_lt=activities[-1]['id'])['results']

# Reading a notification feed is very similar
chris = client.feed('notification', 'chris')
notifications = chris.get(limit=10)['results']

// read the timeline for jack
timelineJack := client.FlatFeed("timeline", "jack")
resp, err := timelineJack.GetActivities(stream.WithActivitiesLimit(10))
if err != nil {
    panic(err)
}
for _, activity := range resp.Results {
    // ...
}
// read the next page, use id filtering for optimal performance
nextResp, err := timelineJack.GetNextPageActivities(resp)
if err != nil {
    panic(err)
}
for _, activity := range nextResp.Results {
    // ...
}
// reading a notification feed is very similar
notificationChris := client.NotificationFeed("notification", "chris")
notificationResp, err := notificationChris.GetActivities(stream.WithActivitiesLimit(10))
if err != nil {
    panic(err)
}
for _, result := range notificationResp.Results {
    for _, activity := range result.Activities {
        // ...
    }
}

var jackTimeline = client.Feed("timeline", "jack");

// Read the timeline for jack
var activities = await jackTimeline.GetActivities(0, 10);
// Read the next page, use id filtering for optimal performance
var nextActivities = await jack.GetActivities(0, 10, FeedFilter.Where().IdLessThan(activities.Last().Id));

// Reading a notification feed is very similar
chris = client.Feed("notification", "chris");
var notifications = await chris.GetActivities(0, 10);

The notification feed also includes the count of unseen and unread activities.

Step 6: Realtime changes

Stream allows you to listen to feed changes in realtime. You can use either websockets, SQS queues or Webhooks to receive notifications.

# read + write token for feed user:1
token = client.feed('user', '1').token
# Generating tokens for client side usage
readonly_token = client.feed('user', '1').readonly_token

// read + write token for feed user:1
var token = client.feed('user', '1').token;
// creates a readonly token for feed user:1
var readonlyToken = client.feed('user', '1').getReadOnlyToken();

# read + write token for feed user:1
token = user_feed_1.token
# readonly token
readonly_token = user_feed_1.get_readonly_token()

// read + write token for feed user:1
$token = $userFeed1->getToken();

// creates a read-only token for feed user:1
$readonlyToken = $userFeed1->getReadonlyToken();

// read and write token for feed user:1
String token = userFeed1.getToken();

// readonly token
String readOnlyToken = userFeed1.getReadOnlyToken();

// read + write token for feed user:1
token := userFeed.RealtimeToken(false)
// readonly token
readonlyToken := userFeed.RealtimeToken(true)

As a next step you want to use this token in your Javascript code and listen to feed changes:

<script type="text/javascript">
    function failCallback(data) {
        alert('something went wrong, check the console logs');
        console.log(data);
    }

    user1 = client.feed('user', '1', token);
    var subscription = user1.subscribe(function callback(data) {
        alert(data);
    }).then(null, failCallback);

    // The returned Subscription object has a method cancel
    // that will remove the listener from this channel 
</script>

This tutorial explains how easy it is to build a notification feed with Stream.

Step 1: Initialize your notification system

To start, we'll describe how to notify 'Scott' that his colleague 'Josh' started following him. The code shows you how to connect to Stream and add an activity with the verb "follow". (Note: You can lookup your API key and secret in the dashboard.)

# pip install stream-python
import stream
client = stream.connect('YOUR_API_KEY', 'API_KEY_SECRET', location='us-east')
# add an activity to Scott's notification feed
notification_feed_scott = client.feed('notification', 'scott')
activity_data = {'actor': 'Josh', 'verb': 'follow', 'object': 'Scott', 'time': '2018-05-04T20:24:03.042927'}
activity_response = notification_feed_scott.add_activity(activity_data)

Step 2: Reading the notification feed

Now, read Scott's notification feed to see how it looks:

# Read Scott's notification feed
scott = client.feed('notification', 'scott')
notifications = scott.get(limit=10)
print(notifications)

{
  "duration": "7.22ms",
  "next": "",
  "results": [
    {
      "activities": [
        {
          "actor": "Josh",
          "foreign_id": "",
          "id": "6ce847e8-4fd7-11e8-9750-121fdba36dae",
          "object": "Scott",
          "origin": null,
          "target": "",
          "time": "2018-05-04T20:24:03.042927",
          "verb": "follow"
        }
      ],
      "activity_count": 1,
      "actor_count": 1,
      "created_at": "2018-05-04T20:24:03.042927",
      "group": "follow_2018-05-04",
      "id": "6cea1419-4fd7-11e8-8080-8001511b5cbe.follow_2018-05-04",
      "is_read": false,
      "is_seen": false,
      "updated_at": "2018-05-04T20:24:03.042927",
      "verb": "follow"
    }
  ],
  "unread": 1,
  "unseen": 1
}
            

Now, bring your attention to the following details within the response: the notification counts and the group. You will see the notification counts in the response: 'unread': 1 and 'unseen': 1. Many notification systems will differentiate between a notification that has been seen as opposed to a notification that has been marked read. The design below highlights the common features of a notification feed:

Notice that each notification contains a list of activities. The activities are grouped together based on the rule set and defined within your Stream dashboard. Note: the group name of follow_2018-05-04 currently contains 1 activity. By default, aggregation groups are based on the activity's verb and time. For example, if multiple people follow you on the same day, there will only be 1 notification. This allows you to show a notification like: "Josh and 3 others followed you". Aggregation helps reduce noise within the notification feed, which is especially important when there's an abundance of user engagement. You can configure or disable the exact rules for how activites are grouped together in the dashboard.

Step 3: Realtime notification system

Stream includes support for listening to changes to your notification feed in real-time. You can listen to changes using Websockets, SQS or webhooks. The example below shows how to use websockets to update the feed in real time. The first step is to generate a token for authorizing the client-side connection for reading the feed.

token = client.feed('notification', 'scott').get_readonly_token()
print(token)

Next, use the token to connect to Stream's websocket infrastructure. Create a file called test.html and paste the following code (remember to use the token you generated above):

<html>
<script src="https://cdn.jsdelivr.net/npm/getstream/dist/js_min/getstream.js"></script>
<script type="text/javascript">
    var token = 'your-token-here';
    var client = stream.connect('YOUR_API_KEY', null, 'SITE_ID');
    var notificationScott = client.feed('notification', 'scott', token);

    function callback(data) {
        alert('A new activity: ' + JSON.stringify(data));
    }

    function successCallback() {
        alert('Now listening to changes in realtime. Add an activity to see how realtime works.');
    }

    function failCallback(data) {
        alert('Something went wrong, check the console logs');
        console.log(data);
    }

    notificationScott.subscribe(callback).then(successCallback, failCallback);
</script>
</html>

Step 4: Follow relationships

At this point, you should have a good understanding of how to add content directly to a user's notification feed. However, there are many use cases for which you may want to notify a group of users. Some examples include:

• Site wide announcements to all users.
• New lectures or homework assignments for a class of students.
• Tickets going on sale for your favorite artist.
• A new event for the group/meetup you follow.

For these types of use cases we recommend creating follow relationships. Let's use the meetup scenario as an example. The code below shows how to follow the golang meetup. It also shows how to create a new event activity for the meetup. Now, you've probably noticed the "meetup" feed group isn't configured at this point. To do so, head over to the dashboard and configure a flat feed group called "meetup".

client.feed('notification', 'scott').follow('meetup', 'golang')
# Scott will now receive notifications about new activities added to the golang meetup feed
activity_data = {'actor': 'Jimmy', 'verb': 'add', 'object': 'event:123', 'event': {'name': 'golang package manager changes', 'location': 'Boulder'}, 'time': '2018-05-04T20:24:03.042927'}
activity_response = client.feed('meetup', 'golang').add_activity(activity_data)

Step 5: Read the feed again

To see what has changed, take a look at the feed. You'll notice the event announcement is now present in Scott's feed. In addition, the activities were not grouped together. The event announcement is in group 'add_2018-05-04' and the follow notification is in group 'follow_2018-05-04'. The follow relationship is very convenient for when many people need to be notified.

# Read Scott's notification feed and mark the notifications as seen
notifications = client.feed('notification', 'scott').get(limit=10, mark_seen=True)
print(notifications)

{
  "duration": "9.98ms",
  "next": "",
  "results": [
    {
      "activities": [
        {
          "actor": "Jimmy",
          "event": {
            "date": "3rd of March 2025",
            "name": "golang package manager changes"
          },
          "foreign_id": "",
          "id": "16008049-4fd9-11e8-9959-121fdba36dae",
          "object": "event:123",
          "origin": "meetup:golang",
          "target": "",
          "time": "2018-05-04T20:24:03.042927",
          "verb": "add"
        }
      ],
      "activity_count": 1,
      "actor_count": 1,
      "created_at": "2018-05-04T20:24:03.042927",
      "group": "add_2018-05-04",
      "id": "16014de8-4fd9-11e8-8080-800162bf0445.add_2018-05-04",
      "is_read": false,
      "is_seen": true,
      "updated_at": "2018-05-04T20:24:03.042927",
      "verb": "add"
    },
    {
      "activities": [
        {
          "actor": "Josh",
          "foreign_id": "",
          "id": "6ce847e8-4fd7-11e8-9750-121fdba36dae",
          "object": "Scott",
          "origin": null,
          "target": "",
          "time": "2018-05-04T20:24:03.042927",
          "verb": "follow"
        }
      ],
      "activity_count": 1,
      "actor_count": 1,
      "created_at": "2018-05-04T20:24:03.042927",
      "group": "follow_2018-05-04",
      "id": "6cea1419-4fd7-11e8-8080-8001511b5cbe.follow_2018-05-04",
      "is_read": false,
      "is_seen": true,
      "updated_at": "2018-05-04T20:24:03.042927",
      "verb": "follow"
    }
  ],
  "unread": 2,
  "unseen": 2
}
          

Step 6: Marking notifications as seen

Did you notice how the request above marked the notification as seen? Note how reading the feed and marking the items as seen is combined in 1 API call. This is convenient since most notification feeds mark items as seen the same moment you open the feed.

When you read the feed again you'll see the notifications changed to 'seen'. You can also mark notifications as 'read'. This is typically done when a user clicks on a notification. The example below shows this process in action:

# Mark an activity as read
notifications = client.feed('notification', 'scott').get(mark_read=["insert-your-notification-id-here"])
# The notification id looks like this: 16014de8-4fd9-11e8-8080-800162bf0445.add_2018-05-04

{
  "duration": "12.10ms",
  "next": "",
  "results": [
    {
      "activities": [
        {
          "actor": "Jimmy",
          "event": {
            "date": "3rd of March 2025",
            "name": "golang package manager changes"
          },
          "foreign_id": "",
          "id": "16008049-4fd9-11e8-9959-121fdba36dae",
          "object": "event:123",
          "origin": "meetup:golang",
          "target": "",
          "time": "2018-05-04T20:24:03.042927",
          "verb": "add"
        }
      ],
      "activity_count": 1,
      "actor_count": 1,
      "created_at": "2018-05-04T20:24:03.042927",
      "group": "add_2018-05-04",
      "id": "16014de8-4fd9-11e8-8080-800162bf0445.add_2018-05-04",
      "is_read": false,
      "is_seen": true,
      "updated_at": "2018-05-04T20:24:03.042927",
      "verb": "add"
    },
    {
      "activities": [
        {
          "actor": "Josh",
          "foreign_id": "",
          "id": "6ce847e8-4fd7-11e8-9750-121fdba36dae",
          "object": "Scott",
          "origin": null,
          "target": "",
          "time": "2018-05-04T20:24:03.042927",
          "verb": "follow"
        }
      ],
      "activity_count": 1,
      "actor_count": 1,
      "created_at": "2018-05-04T20:24:03.042927",
      "group": "follow_2018-05-04",
      "id": "6cea1419-4fd7-11e8-8080-8001511b5cbe.follow_2018-05-04",
      "is_read": false,
      "is_seen": true,
      "updated_at": "2018-05-04T20:24:03.042927",
      "verb": "follow"
    }
  ],
  "unread": 2,
  "unseen": 0
}
          

Step 7: React, JS, Android, iOS and React Native notification systems

We are working on a set of libraries to simplify getting started with frontend development for notification feeds. Shoot us an email describing what you're building and, if available, we'll share an early release.

Concluding the notification system tutorial

We hope you enjoyed this tutorial for building notification systems. If you have any questions please contact us.