Update 09/11/21: Tutorial updated for Pano2VR V6.0.2+
This step-by-step tutorial will take you through the requirements and workflow of posting a 360˚ Panorama to a Twitter Tweet. In it I'll provide information about the Twitter player card, the meta tags required, domain whitelisting, and Twitter Card Validator.
Note: this tutorial assumes a working knowledge of Pano2VR V6.0.2 +
You can download the assets used in this tutorial and follow along with the steps below.
Tutorial Assets: https://tonyredhead.photography/360/twitter/twitter-tutorial-v6.zip
360˚ Panorama in a Tweet
This image below an example of a Twitter Player Card, generated by the tutorial and currently published on my Twitter account
Expanded tweet showing the 360˚ panorama https://twitter.com/tonyredhead/status/1094073834993475584
What is a Twitter player card
A player card is a subset of Twitter Cards. With Twitter Cards, you can attach rich photos, videos and media experience to Tweets that drive traffic to your website. Primarily designed for video clips and audio streams, Player Cards can also provide a unique platform to distribute and share 360˚ Panoramas and Virtual Tours.
1. Getting Started
There are only a few simple requirements needed to display a 360˚ panorama in a Twitter Player Card.
A hosted and self playing 360˚ panorama scalable at 100%
An image that can be used in the initial display
Secure hosting SSL (https://)
A HTML page containing a set of specific Twitter Player Card Meta Tags
Audio content, if incorporated, set to ‘Sound Off’ by default
Note: if you don't have a server that has SSL capabilities I'd recommend checking out Amazon S3 for hosting. Check out my Amazon S3 tutorials for more information.
2. The Assets
In the twitter_tutorial_assets.zip you will find several assets that you can use to create a Pano2VR project suitable for posting on Twitter. The assets are;
Equirectangular image: 8x4_grid.jpg
Skin: twitter-tutorial-v6.ggsk
HTML Template: twitter-tutorial-v6.ggt
Copy the .ggsk and .ggt files into their respective Skin and HTML Template Directories. If you don't know where the directories are, open your Preferences/Files and you can see the locations (figure #1)
Figure #1: Preferences/Files location
Note: if you are on a Mac you can access the locations by 'Option-clicking' the Go menu. Your Library folder appears in the menu; choose Library from the menu to open the folder in the Finder, select 'Application Support/GardenGnomeSoftware/Pano2VR5'
3. Getting Started
1. Create a new folder called 'Twitter Card Tutorial'
2. Launch Pano2VR V6.0.2
3. Save the project into the Twitter Card Tutorial folder as 'Twitter-Card-Project'
3. Create a new HTML5 Output
4. Create an output folder 'tw-card' in the Twitter Card Tutorial folder (figure #2)
5. Select 'twitter-tutorial-v6.ggsk' as the skin (figure #2)
Note: this skin has a mobile and desktop skin. The mobile skin shows just the User Data window and has an option to turn on/off the gyro. The desktop skin has more functionality including the fullscreen option
7. In the 'Output/HTML' section load the twitter-tutorial-v6.ggt file as the Template (figure #2)
8. In the 'Output/Image' section select Single Res and a Cube Face Size of 1,000px (figure #2)
Note: this is just to speed up testing when we upload to our server. When we are ready to publish we can go back to a Multi Res output.
Figure #2: Output Settings
10. Load the 8x4_grid.jpg equirectangular file from the assets folder into the project and save the project (figure #3)
Figure #3: Project saved with assets loaded
4. Twitter Player Card Meta Tags
Specific meta tag data is required in between the <head></head> tags of the html page you will reference in the URL you use for the Twitter post.
The twitter-tutorial-v6.ggsk file is a modified version of the V6 normal.ggsk file that includes the required meta tags as follows:
<meta name="twitter:card" content="player"> <meta name="twitter:site" content="@twittername"> <meta name="twitter:title" content="Panorama Title"> <meta name="twitter:description" content="Description"> <meta name="twitter:image" content="https://yoursite.com/path/preview image"> <meta name="twitter:player" content="https://yoursite.com/path/index.html"> <meta name="twitter:player:width" content="360"> <meta name="twitter:player:height" content="360">
The required information is added, when the project is output, via placeholders and User Data entries. For example, the entry 'tonyredhead' in the 'Copyright' section will replace the '@twittername' with '@tonyredhead' In the tutorial example I will be adding the following information (figure #4)
Figure #4: User Data Information to be applied to the html file
Which results in the following HTML output in the index.html file
<title>Twitter Tutorial</title> <meta name="twitter:card" content="player"> <meta name="twitter:site" content="@tonyredhead"> <meta name="twitter:title" content="Twitter Tutorial"> <meta name="twitter:description" content="A tutorial to create Twitter Large Cards with Pano2VR panoramas"> <meta name="twitter:image" content="https://tonyredhead.photography/360/twitter/tw-card-v6/tw-card-v6.jpg"> <meta name="twitter:player" content="https://tonyredhead.photography/360/twitter/tw-card-v6/index.html"> <meta name="twitter:player:width" content="360"> <meta name="twitter:player:height" content="360">
1. Add the data using your own twitter name, and server path
2. Save the project and output it
3. It should look like this example below
4. Open the index.html file in a text editor, I use TextWrangler but any app will suffice. Make sure that the entries are correct.
5. Adding the Preview Image
The final step is to create a preview image from the equirectangular file.
1. If the project is not already open, open it
2. Create a new 'Transform Output'
3. Set the 'Type:' to 'Rectilinear (default view)'
4. Image Size: 200px x 200px
5. Output Format: JPEG (.jpg), Image Quality: 90
6. Set the Output File to the tw-card folder and name the file $ui.jpg. This will name the output file tw-card.jpg (figure #5)
Figure #5: Transform Output
4. Getting your Domain Whitelisted
Before you can post your URL to Twitter Player Card you have to have the domain whitelisted. Twitter review each Player Card implementation to make sure it fits the guidelines for publishing to their platform. Although they strive for a quick turnaround, they acknowledge that this process sometimes takes longer than expected.
In order to help make the process as smooth and quick as possible, you should verify the following:
You’ve added the proper Twitter Card meta tags to your page, and your page is publicly accessible
The twitter:player and twitter:image URL’s open and play properly in a browser
5. Using the Card Validator
1. Once you have verified the bullet points above open your browser and go the the URL https://cards-dev.twitter.com/validator (figure #6)
Figure #6: Card Validator login
Note: If you are not already logged in to your Twitter account do so now. Once you are logged in the Card Validator window will be displayed.
2. Enter the URL you used in the 'twitter:player' meta tag. In this example I will use https://tonyredhead.photography/360/twitter/tw-card-v6/index.html (figure #7)
Figure #7: Enter index.html url
4. Select ‘Preview Card’. (figure #8)
Note: In the image below the log section is all green and my link is good to be posted. I can click on the 'play' button to see the actual expanded tweet. This is because my domain, tonyredhead.photography, is whitelisted with Twitter.
Figure #8: Previewing the card
Note: If your domain isn’t whitelisted the window will look like the image below and showing an orange 'WARN: Not whitelisted' comment in the Log and a comment under the 'Preview card' button with a ‘Request Approval’ button. (figure #9)
6. To proceed and have your domain whitelisted, select the ‘Request Approval’ button and fill out the information the form requests.
Note: Once you have requested approval and opted-in to having cards displayed, Twitter has to approve the integration. Once approved, you'll get an email confirming that your request has been activated. You can then go back to the Card Validator and you will see a screen similar to that in section #4.
6. Tweeting the Panorama
All that's left now is to actually create a tweet using the URL to your panorama.
1. Log into your Twitter Account if you aren't already logged in
2. Create a new Tweet, add your text and paste in your URL (figure #11)
Figure #11: Compose new Tweet
4. Select Tweet and your tweet will appear at the top of your tweet list (figure #12).
Figure #12: Tweet in the list
Note: you will not see the 360˚ panorama just the reference image and a play button. Twitter doesn't auto-expand tweets with 'card' content except for simple Twitter-hosted images
5. Select the play button and the tweet window will expand to display the 360˚ panorama
Note: at this point you can go back to the HTML project and set the Output > Image > Quality = Multi Res and re-output the project. Don’t forget to upload the output folder to your server to replace the old one.
Summary
I hope you have enjoyed the tutorial and it has helped you to achieve the best possible project outcome. If it has please take a second to consider a donation so that I can continue to add more tutorials.
