Este guia o ajudará a desenvolver aplicativos OpenSocial. Para tirar o máximo proveito deste guia, você deve estar familiarizado com a API do Gadgets e com JavaScript. Este guia também fornece links para outros documentos que trazem mais informações.
Ele foi modificado para refletir as alterações da atualização da API do OpenSocial 0.7. As seções atualizadas possuem o indicador Novo! ou Atualizado para ajudá-lo a identificar as práticas de programação que foram alteradas desde a última versão.
Um site que pode hospedar aplicativos OpenSocial é chamado de recipiente do OpenSocial. Um aplicativo social é um aplicativo executado em um recipiente do OpenSocial.
Para criar um aplicativo OpenSocial, é necessário ter conhecimento da linguagem JavaScript. Como os aplicativos OpenSocial são desenvolvidos como gadgets, é preciso que você saiba como um gadget é estruturado e, para criar seu aplicativo social, você precisará saber mais sobre a API JavaScript do OpenSocial. (Se preferir, você pode criar aplicativos OpenSocial usando uma API RESTful ou RPC.)
Muitos recipientes oferecem outros recursos além dos apresentados na especificação do OpenSocial que você pode usar em seus gadgets. Para saber mais sobre esses recursos específicos do recipiente, consulte a documentação do recipiente listada no Guia Primeiros passos. Além disso, muitos recipientes oferecem ambientes de teste chamados sandboxes, nos quais você pode testar seus gadgets com segurança.
O foco da API do OpenSocial está nas pessoas. Os gadgets OpenSocial ajudam os usuários a compartilharem suas atividades uns com os outros e a acessarem informações de seus amigos. A API do OpenSocial possui três áreas principais de recursos:
Muitas chamadas da API do OpenSocial são assíncronas: ou seja, a chamada é retornada imediatamente, mas a ação solicitada pela chamada não ocorre imediatamente. Em vez disso, a chamada cria uma solicitação ao servidor para recuperar ou atualizar informações. Quando você executa uma chamada assíncrona, você passa uma função de retorno de chamada. Quando os dados são retornados do servidor, o OpenSocial chama sua função de retorno de chamada.
Para obter mais informações sobre os conceitos descritos nesta seção, consulte os seguintes documentos:
Todo gadget tem a seguinte estrutura:
|
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Standard gadget structure">
</ModulePrefs>
<Content type="html">
<![CDATA[
Gadget content and features here
]]>
</Content>
</Module>
Ao criar um gadget que usa OpenSocial, você precisa adicionar a linha abaixo à seção ModulePrefs:
<Require feature="opensocial-0.8"/>
Ela faz com que a estrutura de um gadget OpenSocial seja:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Standard gadget structure">
<Require feature="opensocial-0.8"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
Gadget content and features here
]]>
</Content>
</Module>
Vamos começar com um exemplo simples que lista os nomes dos seus amigos. Primeiro, é importante compreender as funções definidas pela API do OpenSocial:
O exemplo ''List Friends'' (Listar amigos) discutido nesta seção identifica o visualizador e seus amigos e exibe uma lista de amigos do visualizador. Ele ilustra como obter e operar dados em um aplicativo do OpenSocial. As etapas básicas são:
Estas etapas são discutidas abaixo em mais detalhes.
A primeira etapa no desenvolvimento de um gadget é a criação de sua especificação padrão:
<?xml version="1.0" encoding="UTF-8" ?> <Module> <ModulePrefs title="List Friends Example"> <Require feature="opensocial-0.8"/> </ModulePrefs> <Content type="html"> <![CDATA[ <script type="text/javascript"> </script> <div id="message"> </div> ]]> </Content> </Module>
Em seguida, criamos o esqueleto do aplicativo. Ele é composto por duas funções JavaScript que usaremos no gadget:
request, que usaremos para solicitar o proprietário e seus amigos.response, que o OpenSocial chama com os nomes dos amigos do proprietário.
Criaremos as bases para essas funções aqui e as detalharemos nas próximas seções. O elemento final do esqueleto do aplicativo é uma chamada de função que garante que a função request seja executada após o aplicativo ser carregado.
Veja o esqueleto do aplicativo:
<script type="text/javascript">
/**
* Request the OWNER and OWNER's friends.
*/
function request() {
};
/**
* Parses the response and generates html to list the names of the owner and
* his or her friends.
*
* @param {Object} dataResponse Friend information that was requested.
*/
function response(dataResponse) {
};
// Execute the request function when the application is finished loading.
gadgets.util.registerOnLoadHandler(request);
</script>
Em seguida, nós detalharemos a função request, que chama o OpenSocial para obter o proprietário e seus amigos. Esta função:
idspec chamando newIdSpec().req) chamando opensocial.newDataRequest().req.add() para adicionar as funções newFetchPersonRequest() e newFetchPeopleRequest() à solicitação.req.send() para iniciar a solicitação, passando response como a função de retorno de chamada.Ao usar a função newFetchPeopleRequest, você cria um objeto IdSpec que é passado como o argumento da função. O IdSpec que você usa varia de acordo com os dados que deseja recuperar. A tabela abaixo mostra como criar objetos IdSpec para várias solicitações:
| Para solicitar... | Use este código |
|---|---|
| VIEWER_FRIENDS |
var idspec = opensocial.newIdSpec({ "userId" : "VIEWER", "groupId" : "FRIENDS" });
|
| OWNER_FRIENDS |
var idspec = opensocial.newIdSpec({ "userId" : "OWNER", "groupId" : "FRIENDS" });
|
Este é o código para a função request():
/**
* Request the OWNER and OWNER's friends.
*/
function request() {
var idspec = opensocial.newIdSpec({ "userId" : "OWNER", "groupId" : "FRIENDS" });
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest("OWNER"), "get_owner");
req.add(req.newFetchPeopleRequest(idspec), "get_friends");
req.send(response);
};
Observação:Você pode usar strings literais como atalhos para propriedades enums de JavaScript que representam campos e métodos do OpenSocial. Por exemplo, em vez de usar
opensocial.IdSpec.PersonId.OWNER
você pode simplesmente usar
"OWNER"
como no exemplo acima. Para descobrir a string que corresponde a uma propriedade enum, consulte a documentação da propriedade enum na Referência da API JavaScript.
Para obter mais informações sobre newFetchPersonRequest e newFetchPeopleRequest, consulte o artigo Solicitação de dados no OpenSocial.
Nesta seção, criaremos a função response. O servidor chama response() para manipular os dados – o proprietário e seus amigos, desta forma:
dataResponse.get() para inicializá-las com os valores retornados pelo servidor.each().getDisplayName() para cada amigo para adicionar o nome do amigo à saída HTML.person.getDisplayName() para acessar cada um dos amigos e adicione o nome do amigo ao HTML.innerHTML do gadget para o HTML recém criado, chamando document.getElementById('message').innerHTML = html.
/**
* Parses the response and generates html to list the names of the owner and
* his or her friends.
*
* @param {Object} dataResponse Friend information that was requested.
*/
function response(dataResponse) {
var owner = dataResponse.get('get_owner').getData();
var friends = dataResponse.get('get_friends').getData();
var html = 'Friends of ' + owner.getDisplayName();
html += ':<br><ul>';
friends.each(function(person) {
html += '<li>' + person.getDisplayName() + '</li>';
});
html += '</ul>';
document.getElementById('message').innerHTML = html;
};
Esta seção combina os blocos de código anteriores em uma listagem completa para o aplicativo List Friends discutido nesta seção. A função response() obtém o proprietário e seus amigos e depois insere o nome do proprietário em uma string HTML para exibição. A função então acessa os amigos e adiciona o nome de cada amigo ao HTML. Finalmente, o HTML que contém os nomes do proprietário e de seus amigos é inserido na tag div para exibição.
Lista completa:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="List Friends Example">
<Require feature="opensocial-0.8"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
/**
* Request the OWNER and OWNER's friends.
*/
function request() {
var idspec = opensocial.newIdSpec({ "userId" : "OWNER", "groupId" : "FRIENDS" });
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.OWNER), "get_owner");
req.add(req.newFetchPeopleRequest(idspec), "get_friends");
req.send(response);
};
/**
* Parses the response and generates html to list the names of the owner and
* his or her friends.
*
* @param {Object} dataResponse Friend information that was requested.
*/
function response(dataResponse) {
var owner = dataResponse.get('get_owner').getData();
var friends = dataResponse.get('get_friends').getData();
var html = 'Friends of ' + owner.getDisplayName();
html += ':<br><ul>';
friends.each(function(person) {
html += '<li>' + person.getDisplayName() + '</li>';
});
html += '</ul>';
document.getElementById('message').innerHTML = html;
};
// Execute the request function when the application is finished loading.
gadgets.util.registerOnLoadHandler(request);
</script>
<div id="message"> </div>
]]>
</Content>
</Module>
A API do OpenSocial suporta salvar e recuperar dados por usuário e por aplicativo. O código de amostra desta seção:
data1, um número aleatório de 0 a 5, data2, um número aleatório de 0 a 100, e data3, o carimbo de data e hora atual.data1 em AppField1, data2 em AppField2 e data3 em AppField3.Este fragmento de código mostra como salvar os dados nos dados persistentes compartilhados:
/**
* Generate 3 fields of random data and saves them to the persistent data store.
*
*/
function populateMyAppData() {
var req = opensocial.newDataRequest();
var data1 = Math.random() * 5;
var data2 = Math.random() * 100;
var data3 = new Date().getTime();
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField1", data1));
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField2", data2));
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField3", data3));
};
O próximo fragmento de código recupera os dados armazenados através das seguintes etapas:
newFetchPersonAppDataRequest à solicitação, passando os nomes das chaves como parâmetros. req.send para enviar a solicitação ao servidor.
/**
* Use newFetchPersonAppDataRequest() to read data from the store.
*
*/
function requestMyData() {
var req = opensocial.newDataRequest();
var fields = [ "AppField1", "AppField2", "AppField3" ];
var p = {};
p[opensocial.IdSpec.Field.USER_ID[]] = opensocial.IdSpec.PersonId.VIEWER;
var idSpec = opensocial.newIdSpec(p);
req.add(req.newFetchPersonAppDataRequest(idSpec, fields), "viewer_data");
req.send(handleRequestMyData);
}
Aqui está o código completo do aplicativo, que define valores para os três campos, armazena-os e depois os recupera. Esta listagem também adiciona funções para gerar a saída na variável htmlout e depois insere esta variável HTML em um div para exibição.
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Data Persistence Example" >
<Require feature="opensocial-0.8"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<script type="text/javascript">
gadgets.util.registerOnLoadHandler(populateMyAppData);
var htmlout = "";
var me = null;
/**
* Set user data
*/
function populateMyAppData() {
var req = opensocial.newDataRequest();
var data1 = Math.random() * 5;
var data2 = Math.random() * 100;
var data3 = new Date().getTime();
htmlout += "Setting AppField1 to " + data1 + "<br />";
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField1", data1)) + "<br />";
htmlout += "Setting AppField2 to " + data2 + "<br />";
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField2", data2)) + "<br />";
htmlout += "Setting AppField3 to " + data3 + "<br />";
req.add(req.newUpdatePersonAppDataRequest("VIEWER", "AppField3", data3)) + "<br />";
req.send(handlePopulateMyAppData);
}
/**
* Handle responses from update person app data requests
*/
function handlePopulateMyAppData(data) {
if (data.hadError()) {
htmlout += data.getErrorMessage();
}
requestMyData();
}
/**
* Fetch app data
*/
function requestMyData() {
var req = opensocial.newDataRequest();
var fields = [ "AppField1", "AppField2", "AppField3" ];
req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.VIEWER), "viewer");
req.add(req.newFetchPersonAppDataRequest("VIEWER", fields), "viewer_data");
req.send(handleRequestMyData);
}
/**
* Handle responses from app data requests
*/
function handleRequestMyData(data) {
var mydata = data.get("viewer_data");
var viewer = data.get("viewer");
me = viewer.getData();
if (mydata.hadError()) {
htmlout += data.getErrorMessage();
return;
}
// Do something with the returned data - note the getData call
doSomethingWithMyData(mydata.getData());
}
/**
* Operate on user data
*/
function doSomethingWithMyData(data) {
//Data is indexed by user id, and represents an object where keys
//correspond with the app data fields.
var mydata = data[me.getId()];
var div = document.getElementById('content_div');
htmlout += "My AppField1 data is: " + mydata["AppField1"] + "<br />";
htmlout += "My AppField2 data is: " + mydata["AppField2"] + "<br />";
htmlout += "My AppField3 data is: " + mydata["AppField3"] + "<br />";
div.innerHTML = htmlout;
}
</script>
<div id="content_div"></div>
]]>
</Content>
</Module>
Observação: Os dados armazenados em um aplicativo OpenSocial estão sempre na forma de strings. Para a maioria das finalidades, é mais prático que esta string possua codificação JSON. Como o OpenSocial adiciona automaticamente códigos de escape HTML a todos os dados retornados, incluindo dados de aplicativo, é necessário excluir os códigos de escape dos objetos JSON em dados persistentes antes de analisá-los. Por exemplo:
var unescapedString = gadgets.util.unescapeString(jsondata); var obj = gadgets.json.parse(unescapedString);
Existem casos em que seu aplicativo pode precisar excluir uma chave de dados persistentes. Para apagar uma chave e seu valor, use o método newRemovePersonAppDataRequest:
var req = opensocial.newDataRequest();
req.add(
req.newRemovePersonAppDataRequest("VIEWER", "myKey"),
"clear_data");
req.send(set_callback);
Quando esta solicitação é realizada, a chave myKey e seu valor armazenado são apagados dos dados persistentes.
É possível apagar diversas chaves ao mesmo tempo passando uma matriz de chaves a este método:
var req = opensocial.newDataRequest();
req.add(
req.newRemovePersonAppDataRequest("VIEWER", ["key1", "key2", "key3"]),
"clear_data");
req.send(set_callback);
Quando esta solicitação é realizada, as chaves key1, key2, key3 e seus valores armazenados são apagados dos dados persistentes.
Para maiores informações sobre a limpeza de dados persistentes, consulte este artigo sobre o uso de dados persistentes.
A API do OpenSocial permite usar um fluxo de atividades para compartilhar atividades com seus amigos. Um fluxo de atividades é um feed no qual cada entrada representa uma ação realizada pelo usuário. Uma atividade pode ser qualquer coisa, desde modificar o estado de um aplicativo até escrever uma crítica on-line de um filme.
Se você solicitar prioridade de atividade HIGH (alta), o aplicativo solicitará a permissão do usuário para postar as atividades em seu nome, caso ainda não tenha permissão. Se você solicitar prioridade LOW (baixa), a chamada não fará nada se o aplicativo não tiver permissão de postagem.
newActivity para criar uma nova atividade contendo o texto especificado como título.requestCreateActivity para enviar a atividade ao servidor, passando uma função de retorno de chamada.Este exemplo simples ilustra como criar uma atividade:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Activities - v0.8" >
<Require feature="opensocial-0.8"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<div id="content_div"></div>
<script type="text/javascript">
var div = document.getElementById('content_div');
/**
* Create the new activity and send it to the server.
*/
function postActivity(text) {
var params = {};
params[opensocial.Activity.Field.TITLE] = text;
var activity = opensocial.newActivity(params);
opensocial.requestCreateActivity(activity, opensocial.CreateActivityPriority.HIGH, callback);
div.innerHTML = "Activity title is: " + activity.getField(opensocial.Activity.Field.TITLE);
};
/**
* Server calls this function to indicate whether the activity post succeeded or failed.
*/
function callback(status) {
if (status.hadError())
{
alert("Error creating activity.");
}
else
{
alert("Activity successfully created.");
}
};
/**
* Start the process of posting an activity.
*/
function startActivity; {
postActivity("This is a sample activity, created at " + new Date().toString());
};
//Call startActivity as soon as the gadget finishes loading.
gadgets.util.registerOnLoadHandler(startActivity);
</script>
]]>
</Content>
</Module>
A API do OpenSocial suporta o controle de permissão nos aplicativos. Quando um aplicativo usa uma solicitação de dados para obter um visualizador a partir do servidor, essa solicitação só recebe uma resposta se o aplicativo tiver acesso. Se o aplicativo não tiver acesso, é retornado um dos códigos de erro padrão, opensocial.ResponseItem.Error.UNAUTHORIZED. Um aplicativo também pode verificar seu acesso antecipadamente, usando a nova chamada opensocial.hasPermission. Se o acesso for negado, use opensocial.requestPermission para solicitar a permissão especificada ao visualizador. É possível que alguns recipientes sempre concedam e outros sempre neguem acesso ao visualizador, mas esta decisão cabe ao recipiente.
Este trecho ilustra como usar a API de controle de permissão:
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="Checking for Permission" >
<Require feature="opensocial-0.8"/>
</ModulePrefs>
<Content type="html">
<![CDATA[
<h2>Owner:</h2>
<div id="owner-output">No data.</div>
<h2>Viewer:</h2>
<div id="viewer-output">No data.</div>
<script type="text/javascript">
/**
* Request permission for the VIEWER if the app does not have it.
*/
function requestPermission() {
if (opensocial.hasPermission(opensocial.Permission.VIEWER)) {
requestData();
} else {
var reason = "To demonstrate permission capabilities";
opensocial.requestPermission(opensocial.Permission.VIEWER, reason, onPermissionRequested);
}
};
/**
* Handle the response for the request for VIEWER information.
*/
function onPermissionRequested(response) {
if (response.hadError()) {
switch(response.getErrorCode()) {
case opensocial.ResponseItem.Error.NOT_IMPLEMENTED :
alert("Requesting permission is not implemented on this container.");
break;
default:
alert("There was a problem requesting permission: " + response.getErrorMessage());
break;
};
}
requestData();
};
/**
* Request the OWNER (and VIEWER if we have permission).
*/
function requestData() {
var req = opensocial.newDataRequest();
req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.OWNER), "owner");
// If we have permission to see the viewer's info, then add it to the request.
if (opensocial.hasPermission(opensocial.Permission.VIEWER)) {
req.add(req.newFetchPersonRequest(opensocial.IdSpec.PersonId.VIEWER), "viewer");
}
req.send(showData);
};
/**
* Shows the response from the request for Person data.
*/
function showData(data) {
var owner = data.get("owner").getData();
var ownerOutput = document.getElementById("owner-output");
showPerson(owner, ownerOutput);
if (opensocial.hasPermission(opensocial.Permission.VIEWER)) {
var viewer = data.get("viewer").getData();
var viewerOutput = document.getElementById("viewer-output");
showPerson(viewer, viewerOutput);
}
}
/**
* Prints information about a person.
*/
function showPerson(person, div) {
var name = person.getDisplayName();
var thumb = person.getField(opensocial.Person.Field.THUMBNAIL_URL);
var html = '<img src="' + thumb + '"/>' + name;
div.innerHTML = html;
}
//Execute requestData when the page is done loading
gadgets.util.registerOnLoadHandler(requestPermission);
</script>
]]>
</Content>
</Module>
Consulte estes recursos adicionais para saber mais sobre a API do OpenSocial:
| Revisão | Atualizado | Descrição |
|---|---|---|
| OpenSocial 0.8.1 | Setembro de 2008 | A maioria das seções foi atualizada. As instruções do tipo Require foram alteradas para 0.8. A amostra de acesso agora usa IdSpec. Foram adicionadas informações sobre a limpeza de dados persistentes. Amostra de permissões atualizada. |
| OpenSocial 0.7 | Abril de 2008 | Novo documento. |