Advanced Uses

Audience Targeting

Include and exclude specific audiences from viewing your Live Video.

Create a Target Audience

Node

Before You Start

For live videos on a Page, you will need:

For live videos in a Group, you will need:

Examples

Send a POST /id request where id is the LiveVideo ID and set the targeting field and its parameters.

curl -i -X POST \
  "https://graph.facebook.com/LIVE_VIDEO_ID
    ?targeting={age_min:17, geo_locations:{countries:["US","CA","MX"]}}
    &access_token=ACCESS_TOKEN"
GraphRequest request = GraphRequest.newPostRequest(
  accessToken,
  "/LIVE_VIDEO_ID/",
  new JSONObject("{}"),
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/LIVE_VIDEO_ID/"
           parameters:@{ @"targeting": @"{age_min:17, geo_locations:{countries:["US","CA","MX"]}, excluded_zipcodes:{"key":"US:10001"}}",}
           HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/LIVE_VIDEO_ID/',
  'POST',
  {"targeting":"{age_min:17, geo_locations:{countries:[\"US\",\"CA\",\"MX\"]}, excluded_zipcodes:{\"key\":\"US:10001\"}}"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->post(
    '/LIVE_VIDEO_ID/',
    array (
      'targeting' => '{age_min:17, geo_locations:{countries:["US","CA","MX"]}, excluded_zipcodes:{"key":"US:10001"}}'
    ),
    'ACCESS_TOKEN'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();

Sample Response

{
  "targeting": {
    "age_max": 65,
    "age_min": 17,
    "geo_locations": {
      "countries": [
        "US",
        "CA",
        "MX"
      ]
    }
  },
  "id": "LIVE_VIDEO_ID"   
}

Get Target Audience Information

Node

Before You Start

For live videos on a Page, you will need:

For live videos on a Group, you will need:

  • A User access token requested by an admin of the group

Examples

Send a GET /id request where id is the LiveVideo ID with the targeting field.

GraphRequest request = GraphRequest.newGraphPathRequest(
  accessToken,
  "/LIVE_VIDEO_ID",
  new GraphRequest.Callback() {
    @Override
    public void onCompleted(GraphResponse response) {
      // Insert your code here
    }
});

Bundle parameters = new Bundle();
parameters.putString("fields", "targeting");
request.setParameters(parameters);
request.executeAsync();
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
    initWithGraphPath:@"/LIVE_VIDEO_ID"
           parameters:@{ @"fields": @"targeting",}
           HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // Insert your code here
}];
FB.api(
  '/LIVE_VIDEO_ID',
  'GET',
  {"fields":"targeting"},
  function(response) {
      // Insert your code here
  }
);
try {
  // Returns a `FacebookFacebookResponse` object
  $response = $fb->get(
    '/LIVE_VIDEO_ID',
    'ACCESS_TOKEN'
  );
} catch(FacebookExceptionsFacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(FacebookExceptionsFacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
curl -i -X GET \
  "https://graph.facebook.com/LIVE_VIDEO_ID
    ?fields=targeting&access_token=ACCESS_TOKEN"

Sample Response

{
  "targeting": {
    "age_max": 65,
    "age_min": 17,
    "geo_locations": {
      "countries": [
        "US"
        "CA",
        "MX"
      ]
    }
  },
  "id": "LIVE_VIDEO_ID"       
}

Frame-Accurate Go-Live

There can be a slight delay before a broadcast goes live while we decode its initial streaming data and process any associated API requests. This can make it difficult for on-air talent to know exactly when a broadcast has started. To avoid this problem, LiveVideo objects can be set to accept streaming data but to not go live to audiences until a go-live RTMP message is detected within the streaming data itself. This allows anyone who is able to preview a broadcast to see it, while allowing the streaming encoder to precisely control both the time at which the broadcast goes live for an audience and the first frame that the audience sees.

To enable frame-accurate go-live, first create a LiveVideo object as you normally would and set its status to PREVIEW. Once it has been created, query the LiveVideo object and request the secure_stream_url field with the following nested fields:

secure_stream_url.inband_go_live(require_inband_signal)

This will enable frame-accurate go-live on the LiveVideo object and the API will respond with a new secure stream URL which you can then stream to. You can disregard the initial secure stream url that was sent to you when you first created the LiveVideo object.

The broadcast will go live and be visible to the audience after (1) the broadcast status is set to LIVE (through a Graph API call or a user publishing from Live Producer) and (2) the encoder sends the go-live RTMP message.

Go-Live RTMP Message Structure

An AMF0 packet (type 0x12) containing:

  • the string onGoLive
  • an ECMA array (type 0x08) containing a single key-value pair:
    • Key: string (type 0x02) timestamp
    • Value: number (type 0x00): the timestamp of the first video frame that will be publicly visible

For more information, see the RTMP and AMF0 specifications.

Sample Request

Sample request to enable frame-accurate go-live on a LiveVideo.

curl -i -X GET \
   "https://graph.facebook.com/v12.0/LIVE_VIDEO_ID?fields=secure_stream_url.inband_go_live(require_inband_signal)&access_token=12345..."

Sample Response

Secure stream URL for a LiveVideo object with frame-accurate go-live enabled.

{
  "secure_stream_url": "rtmps://rtmp-pc.facebook.com:443/rtmp/LIVE_VIDEO_ID?s_bl=1&s_gl=1&...",
  "id": "LIVE_VIDEO_ID"
}

Go Live Dialog

Beginning May 25, 2021, the Go Live Dialog will be deprecated. Please visit our Blog post for more information.

We've created a plugin to make the process of Live API integration as easy as possible enabling you to authenticate with Facebook, preview your live stream, and describe your live stream through a pop-up window before going live. This dialog is best suited for those streaming from the client side. Backend integrations should continue to use the API directly.

Requirements

To initialize a pop-up window with controls that determine where to direct your POST response insert the following code.

<button id="liveButton">Create Live Stream To Facebook</button>
<script>
document.getElementById('liveButton').onclick = function() {
  FB.ui({
    display: 'popup',
    method: 'live_broadcast',
    phase: 'create',
}, function(response) {
    if (!response.id) {
      alert('dialog canceled');
      return;
    }
    alert('{your-stream-url}:' + response.secure_stream_url);
    FB.ui({
      display: 'popup',
      method: 'live_broadcast',
      phase: 'publish',
      broadcast_data: response,
    }, function(response) {
    alert("video status: \n" + response.status);
    });
  });
};
</script>
Parameters Value Description

display

popup, iframe

How the dialog is open in your web page.

phase

create, publish

Dialog in create phase allows you to get stream url to upload video; Dialog in publish phase will provide preview and go live button. required

broadcast_data

The response object returned from either API or create phase.

This parameter is required for publish phase.

In the Create phase pop-up window, choose the live stream destination which can be on any pages or groups you manage. The POST response will include the stream_url and secure_stream_url fields. Either one can be broken out into a server URL and stream key.

The server URL is the first half of the stream_url: rtmp://rtmp-api.facebook.com:80/rtmp/

The stream key is the latter half of the stream_url: 10153307708286557?ds=1&a=AdrRKk4mOaqPbQdxDuk

Response FieldPhaseDescription

id

create, publish

The ID of broadcast video.

stream_url

create

A rtmp url that contains stream server and stream key used to upload the live stream.

secure_stream_url

create

A rtmps url, the stream url with secure protocol.

status

publish

String value indicating the status of broadcast.

In our code snippet, we have an alert call with the stream_url. Your client should start streaming using stream_url. Soon after the stream starts, you will notice a preview of the broadcast appear in the publish phase pop-up window. The dialog enables users to choose privacy settings without adjusting the request's privacy parameter and to set the Live video description, title, and topic tags.

Note: If the publish pop-up window is Offline, ensure that your firewall is not blocking RTMP and that any Adblocker software on your browser is turned off.

When you click Go Live, the dialog will close and within a few seconds, the live stream play on the page or group, according to the chosen destination.

Metadata is injected into the first frame of a live video with frame-accurate start times. Encoders can implement a countdown to alert publishers to the exact start of the video. You can also start and stop the video from the Facebook interface.