Javascript

Learn How Easy It Can Be To Build Scalable Newsfeeds and Activity Streams

Copied!

Stream has official clients for JS/Node, Ruby, Python, PHP, Go, and Java. There are framework integrations available for Rails, Django, Laravel, Doctrine, Zend, and Node. In addition to the official clients, the community has built clients for .NET and Scala.

Integrations

Copied!

Official Clients

Copied!

Official clients are currently available for a number of languages:

Community Clients

Copied!

The community also contributed clients for Scala and Elixir:

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

Framework Integrations

Copied!

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.

Community Framework Projects

Copied!

The community also contributed the following example projects

Setup

Copied!

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

1
2
3
4
5
6
7
8
// install via npm 
npm install getstream 
 
// or yarn 
yarn add getstream 
 
// or download the UMD built version from Github 
https://raw.githubusercontent.com/GetStream/stream-js/master/dist/js/getstream.js
1
2
3
4
5
# install directly with gem 
gem install "stream-ruby" 
 
# or add this to your Gemfile and then run bundler 
gem "stream-ruby"
1
// pip install stream-python
1
2
// install using composer 
composer require get-stream/stream
1
2
3
4
5
6
7
// Add the following dependency and repository to your pom.xml file 
 
<dependency> 
    <groupId>io.getstream.client</groupId> 
    <artifactId>stream-java</artifactId> 
    <version>3.0.0</version> 
</dependency>
1
2
3
4
5
// 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"
1
2
3
4
5
// CocoaPods 
pod 'GetStream', '~> 2.0' 
 
// Carthage 
github "GetStream/stream-swift"
All source code can be found on GitHub.

To instantiate the client you need an API key and secret. You can find the key and secret on the dashboard. The examples below already include your key and secret.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const stream = require('getstream'); 
 
// instantiate a new client (server side) 
const client = stream.connect( 
  'YOUR_API_KEY', 
  'YOUR_API_SECRET' 
); 
 
// OR 
 
import stream from 'getstream'; 
 
const client = stream.connect( 
  'YOUR_API_KEY', 
  'YOUR_API_SECRET' 
);
1
2
3
4
# Instantiate a new client (server side) 
require 'stream' 
client = Stream::Client.new('YOUR_API_KEY', 'YOUR_API_SECRET', :location => 'us-east') 
# Find your API keys here https://getstream.io/dashboard/
1
2
3
4
# Instantiate a new client (server side) 
import stream 
client = stream.connect('YOUR_API_KEY', 'YOUR_API_SECRET', location='us-east') 
# Find your API keys here https://getstream.io/dashboard/
1
2
3
// Instantiate a new client (server side) 
$client = new GetStream\Stream\Client('YOUR_API_KEY', 'YOUR_API_SECRET'); 
// Find your API keys here https://getstream.io/dashboard/
1
2
3
4
5
6
// import io.getstream.client.Client; 
 
Client client = Client.builder( 
  'YOUR_API_KEY', 
  'YOUR_API_SECRET' 
 ).build();
1
2
3
4
5
6
7
8
import ( 
    stream "gopkg.in/GetStream/stream-go2.v1" 
) 
 
client, err := stream.NewClient( 
    'YOUR_API_KEY', 
    '{{ api_secret }}', 
)
1
2
3
4
// import GetStream 
 
// Setup Stream client (server side) 
let client = Client(apiKey: "YOUR_API_SECRET", appId: "APP_ID", token: "FEED_TOKEN")

If you want to use Stream on your mobile or web application, you need to generate a token server-side that the JS/Swift/Java client can use to authenticate as a user of your application.

Generate User Token Server-Side

Copied!

This code generates the token for one of your users; a common place to do this is at signup or login. The token is then passed to the frontend.

1
const userToken = client.createUserToken('the-user-id');
1
user_token = client.create_user_session_token('the-user-id')
1
user_token = client.create_user_token('the-user-id')
1
$userToken = client->createUserSessionToken("the-user-id");
1
Token userToken = client.frontendToken("the-user-id");
1
Token userToken = client.frontendToken("the-user-id");

Use Stream API client-side (JS, Swift)

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
const stream = require('getstream'); 
 
// Instantiate new client with a user token 
const client = stream.connect( 
  'YOUR_API_KEY',  
  'FEED_TOKEN', 
  'APP_ID' 
); 
 
// OR 
 
import stream from 'getstream'; 
 
const client = stream.connect( 
  'YOUR_API_KEY',  
  'FEED_TOKEN', 
  'APP_ID' 
);
1
2
3
4
5
6
7
8
// import GetStream 
 
// Setup Stream client. 
let client = Client( 
  apiKey: "YOUR_API_KEY",  
  appId: "APP_ID",  
  token: "FEED_TOKEN" 
)

Quick Start

Copied!

The quick start below shows you how to build a scalable social network. It highlights the most common API calls:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
const chris = client.feed('user', 'chris'); 
 
// Add an Activity; message is a custom field - tip: you can add unlimited custom fields! 
await chris.addActivity({ 
    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: 
const jack = client.feed('timeline', 'jack'); 
await jack.follow('user', 'chris'); 
 
 
// Read Jack's timeline and Chris' post appears in the feed: 
const results = await jack.get({ limit: 10 }); 
 
// Remove an Activity by referencing it's Foreign Id: 
await chris.removeActivity({ foreignId: 'picture:10' });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
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)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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")
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
FlatFeed chris = client.flatFeed("user", "chris"); 
// Add an Activity; message is a custom field - tip: you can add unlimited custom fields! 
chris.addActivity(Activity.builder() 
        .actor("chris") 
        .verb("add") 
        .object("picture:10") 
        .foreignID("picture:10") 
        .extraField("message", "Beautiful bird!") 
        .build()); 
 
// Create a following relationship between Jack's "timeline" feed and Chris' "user" feed: 
FlatFeed jack = client.flatFeed("timeline", "jack"); 
ack.follow(chris).join(); 
 
// Read Jack's timeline and Chris' post appears in the feed: 
List<Activity> response = jack.getActivities(new Pagination().limit(10)).join(); 
for (Activity activity : response) { 
        // ... 
} 
 
// Remove an Activity by referencing it's foreign_id 
chris.removeActivityByForeignID("picture:10").join();
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
chris, err := client.FlatFeed("user", "chris") 
if err != nil { 
    panic(err) 
} 
 
// 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, err := client.FlatFeed("timeline", "jack") 
if err != nil { 
    panic(err) 
} 
 
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) 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
$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);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// Setup a shared Stream Client. 
let client = Client(apiKey: "YOUR_API_SECRET", appId: "APP_ID", token: "FEED_TOKEN") 
 
// Setup a Stream user, when your user was logged in. 
Client.shared.setupUser(token: token) { _ in  
    // Do all your requests from here. Reload feeds and etc. 
} 
 
// Create a user feed. 
// ⚠️ Make sure your feeds are instance variables to wait for the result: `var userFeed: FlatFeed?` 
userFeed = Client.shared.flatFeed(feedSlug: "user") 
 
// Create an Activity. You can make own Activity class or struct with custom properties. 
let activity = Activity(actor: User.current!, verb: "add", object: "picture:10", foreignId: "picture:10") 
 
userFeed?.add(activity) { result in 
    // A result of the adding of the activity. 
    print(result) 
} 
 
// Create a following relationship between "timeline" feed and "user" feed: 
timelineFeed = Client.shared.flatFeed(feedSlug: "timeline") 
 
timelineFeed?.follow(toTarget: userFeed!.feedId, activityCopyLimit: 1) { result in 
    print(result) 
} 
 
// Read timeline and user's post appears in the feed: 
timelineFeed?.get(pagination: .limit(10)) { result in 
    let response = try! result.get() 
    print(response.results) 
} 
 
// Remove an activity by referencing it's foreignId 
userFeed?.remove(foreignId: "picture:10") { result in 
    print(result) 
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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 good deal of information at once. The getting started docs provide a more detailed and interactive explanation.