Difference between revisions of "Snapshot API"

From Second Life Wiki
Jump to navigation Jump to search
 
(25 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{Unsupported API}}
{{:API Portal/navigation}}
{{:API Portal/navigation}}
__TOC__
__TOC__
<br clear=all/>


== Getting Started ==
== Overview ==


=== What is the Snapshot API? ===
[[File:email-snapshot-ui.jpg|200px|thumb|right|Email snapshot of user interface]]
[[File:email-snapshot-ui.jpg|200px|thumb|right|Email snapshot of user interface]]
The Second Life Snapshot API enables you to parse information from Snapshot emails sent from Second Life for:
The Second Life Snapshot API enables you to parse information from [[Snapshot]] emails sent from the viewer for:
* Blogging
* Blogging
* Social Networking
* Social Networking
* Image Libraries
* Image Libraries


=== Where is the Snapshot API used? ===
There are many websites that already use this information. They are listed in the [[Snapshot resources#Social sites featuring snapshots]].
There are many websites that already use this information. Some of them are as follows:
* [http://www.sluniverse.com/pics Snapzilla]
* [http://bloghud.com/ blogHUD]
* [http://mixoom.com/ Mixoom]
* [http://www.koinup.com/ Koinup]


== Structure ==
== Structure ==


=== Headers ===
=== Headers ===
Email messages have headers that provide metadata about the message itself. Most of this information is hidden from the person reading an email message. You can use some of this information to verify that the snapshot came from a Linden Lab server.
Email messages have headers that provide metadata about the message itself. Some of this information is hidden from the person reading an email message. Many email clients permit an individual to look at the "raw" message, in which the hidden headers are exposed. You can use some of this information to verify that the snapshot came from a Linden Lab server.


The following headers are available.
The following headers are available.
Line 32: Line 28:
|X-Originating-IP
|X-Originating-IP
|string
|string
|IP of simulator. [216.82.41.11]
|IP of simulator in brackets. <nowiki>[216.82.41.11]</nowiki>. See [[Simulator_IP_Addresses]] to verify origin.
|-
|-
|Subject
|Subject
Line 49: Line 45:
|date
|date
|Date of snapshot in Pacific timezone.
|Date of snapshot in Pacific timezone.
|-
|Message-ID
|string
|Use this field to prevent multiple attempts to process the same message. This value usually contains the time and the sim that a message was sent from. <nowiki><20100117090229.B6751DF0559@sim9063.agni.lindenlab.com></nowiki>
|}
|}


Line 76: Line 76:
  local_z=56
  local_z=56
  END POSTCARD DETAILS -->
  END POSTCARD DETAILS -->
Each piece of information is based on where the Avatar was standing when the snapshot was taken. You can take a snapshot, and walk to another location before sending the Snapshot. With detached cameras, the image may actually be from a different location than the avatar is standing.


{| style="border:1px solid #A3B1BF; text-align:left; background:#f5faff"
{| style="border:1px solid #A3B1BF; text-align:left; background:#f5faff"
Line 93: Line 95:
|region_id
|region_id
|key
|key
|The UUID of the region that the avatar was standing when the snapshot was taken.
|The UUID of the region.
|-
|-
|sim_name
|sim_name
|string
|string
|Quoted name of the region that the avatar was standing when the snapshot was taken.
|Quoted name of the region.
|-
|-
|global_x
|global_x
|integer
|integer
|The grids horizontal location of where the avatar was standing when the snapshot was taken.
|The East/West [[Grid Coordinates]] of the avatar.
|-
|-
|global_y
|global_y
|integer
|integer
|The grids vertical location of where the avatar was standing when the snapshot was taken.
|The North/South [[Grid Coordinates]] of the avatar.
|-
|-
|local_x
|local_x
|integer
|integer
|The regions horizontal location of where the avatar was standing when the snapshot was taken.
|The East/West [[Coordinate]] of the avatar.
|-
|-
|local_y
|local_y
|integer
|integer
|The regions vertical location of where the avatar was standing when the snapshot was taken.
|The North/South [[Coordinate]] of the avatar.
|-
|local_z
|integer
|The Height [[Coordinate]] of the avatar.
|}
|}
The global coordinates could be used to determine the URL to display for a map tile image defined in the [[Map API]].
The local coordinates and region name can be used to create a [[Slurl]].


==== Message ====
==== Message ====
Line 125: Line 134:


HTML Entities will be encoded. "&lt;" will appear as "&amp;lt;".
HTML Entities will be encoded. "&lt;" will appear as "&amp;lt;".
By default, the message is limited to 700 characters. However, this can be changed as outlined in the [[Advanced Snapshot Tips#Longer Messages]]


==== Referral Bonus ====
==== Referral Bonus ====
Line 131: Line 142:


  http://secondlife.com/ss/?u=123456789abcdef0123456789abcdef0
  http://secondlife.com/ss/?u=123456789abcdef0123456789abcdef0
{{KBnote|Referral bonus is no longer given.}}


==== Snapshot ====
==== Snapshot ====


The snapshot is a JPEG image. Postcards have two images, including a logo. The snapshot file name is always called "secondlife-postcard.jpg".
The snapshot is a JPEG image. Postcards have two images, including a logo. The snapshot file name is always called "secondlife-postcard.jpg". There is not any embedded information (such as [http://en.wikipedia.org/wiki/Exchangeable_image_file_format EXIF]) in the image itself.
 
== Advanced Snapshot Tips ==
 
There are a few tweaks that you can do in order to get the most out of taking snapshots within the Second Life client. Here are a few.
 
=== Multiple Addresses ===
 
The Recipient email field can accept multiple email addresses. You can separate each one with a semicolon.
 
account1@yourdomain.com;account2@yourdomain.com;account3@yourdomain.com
 
=== Populated Addresses ===
 
For those who always send snapshots to the same email addresses, you can edit a file on your file system to populate that information for you.
 
C:\Program Files (x86)\SecondLife\skins\default\xui\en-us\floater_postcard.xml
 
Look for the following and add your email addresses:  
 
<nowiki><text bottom="-35" follows="top|left" font="SansSerif" left="12" name="to_label"></nowiki>
    Recipient&apos;s Email:
<nowiki></text></nowiki>
<nowiki><line_editor bottom_delta="-6" follows="left|top" height="20"</nowiki>
<nowiki>left="120" max_length="254" name="to_form"</nowiki>
<nowiki>width="150" ></nowiki>''account1@yourdomain.com;account2@yourdomain.com;account3@yourdomain.com''<nowiki></line_editor></nowiki>
 
=== Longer Messages ===
 
By default, the message is limited to 700 characters. You can extend this to 6,526 characters by editing a file on your file system.
 
C:\Program Files (x86)\SecondLife\skins\default\xui\en-us\floater_postcard.xml
 
Look for the following and change the max_length property:


<nowiki><text bottom_delta="-23" follows="top|left" font="SansSerif" left="12" name="msg_label"></nowiki>
[[Category:Textures and Snapshots]]
    Message:
<nowiki></text></nowiki>
<nowiki><text_editor bottom_delta="-150" follows="left|top|right|bottom" height="140" left="12"</nowiki>
''max_length="700"'' <nowiki>name="msg_form" width="420"></nowiki>
    Type your message here.
<nowiki></text_editor></nowiki>

Latest revision as of 16:03, 26 May 2011

NOTE: This API and its documentation are NOT provided or supported by Linden Lab. Linden Lab does not guarantee that this API works as described or works at all. Use at your own risk!


Overview

Email snapshot of user interface

The Second Life Snapshot API enables you to parse information from Snapshot emails sent from the viewer for:

  • Blogging
  • Social Networking
  • Image Libraries

There are many websites that already use this information. They are listed in the Snapshot resources#Social sites featuring snapshots.

Structure

Headers

Email messages have headers that provide metadata about the message itself. Some of this information is hidden from the person reading an email message. Many email clients permit an individual to look at the "raw" message, in which the hidden headers are exposed. You can use some of this information to verify that the snapshot came from a Linden Lab server.

The following headers are available.

Parameter Data type Description
X-Originating-IP string IP of simulator in brackets. [216.82.41.11]. See Simulator_IP_Addresses to verify origin.
Subject string Subject of message
Sender string email address of www-data account on simulator. "www-data" <www-data@sim8938.agni.lindenlab.com>
From string Combination of address and name. Note: name is not always avatar name.
Date date Date of snapshot in Pacific timezone.
Message-ID string Use this field to prevent multiple attempts to process the same message. This value usually contains the time and the sim that a message was sent from. <20100117090229.B6751DF0559@sim9063.agni.lindenlab.com>

Body

Snapshots are sent as two parts. The first is plain text, and the second is a multi-part message in MIME format.

  • text/plain
  • multipart/related
    • text/html
    • image/jpeg - secondlife-postcard.jpg
    • image/jpeg - logo_secondlife.jpg

Details

The HTML content within the multi-part message will contain details of the snapshot in a comment tag: 

<!-- BEGIN POSTCARD DETAILS
agent_id=c4822e40-f763-4eec-bba3-e4bf842a074a
username="Dedric Mauriac"
region_id=714a15be-8511-4842-a8c1-38c1f54f3c58
sim_name="Applewood"
global_x=260282
global_y=235143
local_x=186
local_y=135
local_z=56
END POSTCARD DETAILS -->

Each piece of information is based on where the Avatar was standing when the snapshot was taken. You can take a snapshot, and walk to another location before sending the Snapshot. With detached cameras, the image may actually be from a different location than the avatar is standing.

Parameter Data type Description
agent_id key The UUID of the avatar that sent the message.
username string Quoted name of the avatar who sent the message.
region_id key The UUID of the region.
sim_name string Quoted name of the region.
global_x integer The East/West Grid Coordinates of the avatar.
global_y integer The North/South Grid Coordinates of the avatar.
local_x integer The East/West Coordinate of the avatar.
local_y integer The North/South Coordinate of the avatar.
local_z integer The Height Coordinate of the avatar.

The global coordinates could be used to determine the URL to display for a map tile image defined in the Map API. The local coordinates and region name can be used to create a Slurl.

Message

Although you could use the entire HTML source code of a message, it is often not wanted. The original message contains additional information that is not needed. The message that the end-user wrote in the postcard itself is identified with comments: 

<!-- BEGIN POSTCARD BODY -->
test message
<!-- END POSTCARD BODY -->

HTML Entities will be encoded. "<" will appear as "&lt;".

By default, the message is limited to 700 characters. However, this can be changed as outlined in the Advanced Snapshot Tips#Longer Messages

Referral Bonus

Snapshots include a URL to invite others to join them. If a new account is created from following the link, and certain conditions are met, then the sender could receive a bonus. This URL is wrapped around the logo in the message. 

http://secondlife.com/ss/?u=123456789abcdef0123456789abcdef0
KBnote.png Note: Referral bonus is no longer given.

Snapshot

The snapshot is a JPEG image. Postcards have two images, including a logo. The snapshot file name is always called "secondlife-postcard.jpg". There is not any embedded information (such as EXIF) in the image itself.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=Snapshot_API&oldid=1144580"