Update: In August 2022, Twitter removed the preview functionality from the Card Validator. You can read more about this change here https://twittercommunity.com/t/card-validator-preview-removal/175006
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 V5.2.3
You can download the assets used in this tutorial and follow along with the steps below. http://tonyredhead.photography/360/TUTORIALS/twitter_tutorial_assets.zip
360˚ Panorama in a Tweet
This image below an example of a Twitter Player Card currently published on my Twitter account
Expanded tweet showing the 360˚ panorama
https://twitter.com/tonyredhead/status/964861518608154625
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.ggsk
HTML Template: twitter-tutorial.ggt
1. 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
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 V5.2.3
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.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.ggt file as the Template (figure #2)
8. In the 'Edit Template' window (accessed by clicking on the spanner and screwdriver icon) check 'include gyroscope control:' (figure #3)
9. 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
figure #3: Gyroscope control
10. Load the 8x4_grid.jpg equirectangular file from the assets folder into the project and save the project (figure #4)
figure #4: 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.ggsk file is a modified version of the V5 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 #5)
figure #5: User Data Information
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/tw-card.jpg"> <meta name="twitter:player" content="https://tonyredhead.photography/360/twitter/tw-card/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 #6)
figure #6: Transform Output
7. Save the project and output the Transformation
8. The tw-card.jpg file is saved to the tw-card folder (figure #7)
figure #7: preview image saved
9. Upload the tw-card.jpg to the tw-card folder on your server
10. You are now ready to move to Twitter
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 #8)
figure #8: 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. (figure #9)
figure #9: Logged in and ready to enter URL
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/index.html
3. Select ‘Preview Card’
Note: As my domain, tonyredhead.photography, is whitelisted with Twitter. A notice, in green, affirming the whitelisting is displayed and in the 'Log' section all INFO: notifications are green. (figure #10)
figure #10: Preview Card
4. I can click on the 'play' button to see the actual expanded tweet as it will look on Twitter (figure #11)
figure #11: Card Preview
5. 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 (figure #12)
figure #12: Not Whitelisted
6. Select the ‘Request Approval’ button and fill out the information the form requests to have your domain whitelisted (figure #13)
figure #13: Whitelist request
7. Now that 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 figure #10.
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 #14)
figure #14: Compose tweet
3. Select Tweet and your tweet will appear at the top of your tweet list (figure #15)
figure #15: Published tweet
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
4. Select the play button and the tweet window will expand to display the 360˚ panorama (figure #16)
figure #16: Expanded tweet displaying 360˚ panorama
If you have any feedback I'd love to hear it.
regards,
Tony
