This SDK allows developers to integrate Periscope APIs with their Unity applications easily. The SDK provides an authentication flow so users can login with their Periscope account, start / stop broadcast, Go Live and most importantly start interacting with their audience in a new format. If you use this SDK in your application, viewers on Periscope can interact with your application, get immediate feedback and be a part of the experience!
Imagine a VR game where you're no longer alone, you have other people present in the virtual world potentially helping you, or playing the game alongside you. For inspiration please check this out!
This prefab is where all the API calls are handles. It lives as a singleton and it is not destroyed during scene changes. This keeps the current state with respect to all Periscope functionality.
Before you can start making Periscope API calls, you must register your app and acquire a client id. This allows users to know which app they are giving permissions to during authentication. To register your app refer to the Acquiring a Client ID section.
The prefab is pretty much configured to be drag and drop without too much
configuration. The only parameter that you should pay attention to as the
developer is the Min Acceptable Fps. The ideal value for this parameter
changes based on the type of application you're developing. As a rule of thumb,
we found that for VR games value of 75, for desktop games 50 and non-fps
intensive applications 20 works well. The details of what this parameter does
can be found in the FPS-based Parameter Tuning.
Go to Periscope Developer Hub and add click on "Add Application" to add your application to the registry.
Since the popularity of a Periscope broadcast is not known upfront we had to
create a method to throttle incoming / outgoing events (Hearts/Chats/Joins/DMs).
We decided that the frame rate is a good metric to look at to decide if the
Pericope SDK is consuming too much resources, hence degrading the application
performance. This way, Periscope SDK processes events only when the application
can maintain a desired level of frame rate, set by the Min Acceptable Fps on
PeriscopeAPIManager. You can see the stats on PeriscopeAPIManager and
how much throttling is happening and/or how many events are successfully
processed when your application is running in the Unity Editor.
We noticed that a typical use case for the Periscope events is dividing the
audience into groups and have them contribute to the application as part of a
team. For this purpose we created the PeriscopeUserGroupsManager. This prefab
integrates with the PeriscopeAPIManager and consumes individual heart events
from the audience to accumulate them into an AggregatedHeartsEvent. This
prefab tries to maintain an even split between groups, however this is noticed
guaranteed. The group assignment per Periscope viewer is kept constant through
a broadcast, but changes between different broadcasts. This ensures the same
person can leave the broadcast and come back, and remain as part of the same
team. This avoids confusion from the viewer's perspective. On the flip side, the
team assignment may change in between broadcasts, which ensures the same viewer
is not always part of the same group for all broadcasts, which could get boring
very fast.
This prefab also conveniently defines some common DM (Direct Message) templates that allows the application to communicate and give instructions to the viewers. These DMs are sent when viewer joins a group, has not been active for a period of time, when they are expected to be placed in a group but the group is full, when they send hearts or chats, or simply just periodically.
This prefab is used both for the snails and bars examples. Please check them out for a better understanding of how it is utilized.
First, you need to call Authenticate() on PeriscopeAPIManager. This call
will return immediately to unblock the application. You should listen to the
AuthenticationStatus and AuthUrl on PeriscopeAPIManager and wait until
AuthUrl is a valid string and AuthenticationStatus is Waiting. This is
when you should instruct your user to open the url in a browser and enter the
code from AuthCode.
The AuthenticationStatus will convert to Authenticated once the user
successfully logs into their Periscope account and enters the code to give
permission to your application. At this point your application can create, start
and end broadcasts on behalf of your user.
From the API perspective there's a difference between creating and starting a broadcast. When the broadcast is created, the API returns a stream url and key for user to send their video data. At this point the user is not live, until the broadcast is started.
To get the stream info, first call the GetStreamInfo() on
PeriscopeAPIManager. This call will also return immediately to unblock the
application. At this point you should listen to the BroadcastStatus. When the
broadcast creation is successful, BroadcastStatus will become ReadyToStream,
and StreamUrl and StreamKey fields will become valid. Present the values of
StreamUrl and StreamKey to the user and instruct them to start sending their
video data to this RTMP url. The users will have to use one of third party
software that is commonly used for streaming games (e.g.
OBS Studio).
At this point, user is ready to start the broadcast and Go Live. Simply call
the GoLive() on PeriscopeAPIManager with the desired optional parameters.
This method will return immediately as well. When the user has successfully
started the broadcast and is live, the BroadcastStatus will change to Live.
In your development if you were able to come this far, now you are live and you should start having some viewers in your broadcast. Congratulations!! Now you're ready to have your audience be a part of your application and give them a voice and purpose.
Stopping a broadcast is as simple as calling EndBroadcast() on
PeriscopeAPIManager. Mind that this is a valid action only when the
BroadcastStatus is Live. Otherwise the call results in a no-op.
NOTE: For an example implementation of the auth flow as well as broadcast
start / end controls, you can check the PeriscopeMenu component in
snails and bars examples.
It's great that you've come this far because this is where the magic happens. You can now have the Periscope audience participate in your application directly.
To start consuming user events, first you need to connect to the live broadcast
by calling Connect() on PeriscopeAPIManager. This call will return
immediately as well. Once the call is successful the ConnectionStatus will
change to Connected. At this point PeriscopeAPIManager will start consuming
user engagement events.
PeriscopeAPIManager looks for all the implementations of EventsProcessor
that are present in the scene and calls the appropriate functions based on the
incoming events. EventsProcessor is an abstract class that has three
functions:
OnPeriscopeChatEvent(User user, string color, string message)OnPeriscopeHeartEvent(User user, string color)OnPeriscopeJoinEvent(User user, string color)
Responding to these events is as simple as implementing a component that
inherits from EventsProcessor and placing it in the scene. In fact
PeriscopeUserGroupsManager works the same way, and can be used as a sample
implementation.
NOTE: You can listen to the Error field on PeriscopeAPIManager to keeps
and eye on what's wrong. Especially during the development of your application
this can come in handy. If you encounter an error that you're unable to
interpret, please feel free to contact us.
During the development of your application you are unlikely to attract a large number of viewers. However if your users are popular, or your application gains popularity once it's released, you will want to be prepared to handle a large number of incoming / outgoing user events.
For this purpose we are also including a node.js script that may help you
with performance testing. The local_chat_server.js script acts as the
Periscope server and simulates a large number of viewers sending a large number
of various user events.
-
Install websocket via npm -
npm install websocket -
Run local chat server -
node local_chat_server.js -
Enable
Use LocalhostunderPeriscopeAPIManagerprefab and run your scene
Finally we are including a few example scenes to showcase what is possible with this SDK. Feel free to modify them, build your own applications based on them, or simply Go Live with them.
The example scenes are located at sdk/Assets/Examples/Scenes/.
This is a simple snail racing game. It features two beautiful snails, Gary and Liz. The rules are simple, viewers are split into two teams, each team is assigned to a snail and each heart event gives the corresponding team snail. The more hearts, the faster the snails go. But there's a caveat, when the night comes, the snails go backwards!
This is just a simpler version of the snails game that does not have much UI.
This is intended to serve as a barebones application that demonstrate how
PeriscopeAPIManager, PeriscopeUserGroupsManager and PeriscopeMenu come
together. This is a good starting point to inspect code and understand the
SDK.
The viewers are again split into two teams in this scene, each team controlling a bar. The bars increase or decrease based on the number of hearts viewers send. The increase / decrease behavior is toggled every 3 seconds.