EC-CUBE 4.2 / 4.3 対応公式マニュアル

商品メディアギャラリープラグイン

商品詳細ページを高画質画像・動画（MP4/WebM）・YouTube・Vimeoに対応したリッチメディアギャラリーへアップグレード。3D拡大鏡ズーム、スマホスワイプ、共有メディアライブラリ、SEO構造化データ出力までを網羅した最高級ギャラリー管理プラグインです。

1. プラグイン概要と主な機能

『商品メディアギャラリープラグイン (ProductMediaGallery)』は、EC-CUBE標準の画像管理を大幅に拡張し、動画や外部ストリーミング動画（YouTube/Vimeo）の埋め込み、滑らかなズーム閲覧体験、そしてショップ全体の素材管理効率化を実現します。

多種メディア形式に対応

高解像度画像（WebP対応）、自社MP4/WebM動画、YouTube（Shorts対応）、Vimeoをシームレスに統合。

4種のレイアウトプリセット

縦型、横型、インスタグラム風グリッド、タッチスライダーからショップに合うスタイルをワンクリック選択。

3D拡大鏡ズーム (Magnifier)

PC上でマウスを重ねると2.5倍のガラスレンズが出現。商品の質感・ディテールを忠実に伝えます。

スマホ最適化タッチスワイプ

実機スマートフォンでの滑らかな指先スワイプ操作と弾性スプリングエフェクトを標準搭載。

共有メディアライブラリ

他商品でアップロードした素材を再利用。サーバーディスク容量を消費せずワンクリックで新商品へ登録。

Schema.org JSON-LD SEO

Google検索エンジン向けにImageObject/VideoObject構造化データを自動出力し、リッチリザルト獲得を支援。

2. インストール・有効化

EC-CUBE管理画面の「オーナーズストア」経由、またはCLIコマンドから簡単に導入できます。

オーナーズストアからインストール

管理画面 → オーナーズストア → プラグイン一覧 より「ProductMediaGallery」をインストールし、有効化を完了してください。

（開発者向け）CLIコマンドでのインストール

# プラグインのインストール
bin/console eccube:plugin:install --code=ProductMediaGallery

# プラグインの有効化（マイグレーション自動実行）
bin/console eccube:plugin:enable --code=ProductMediaGallery

# プロキシファイルの再生成
bin/console eccube:generate:proxies

# アセットファイルの同期
bin/console eccube:plugin:assets:install

# キャッシュクリア
bin/console cache:clear --no-warmup

3. メディアギャラリー表示設定

管理画面 → 商品管理 → メディアギャラリー設定 を開き、ショップのフロントエンドにおける表示スタイルや動作機能をノーコードで設定します。

1. レイアウトパターン (4種類)

レイアウト形式	特徴・おすすめの活用シーン
サムネイル左配置（標準縦型）	左側にサムネイルが縦に並び、右側にメイン画像が表示されます。アパレルやブランドECに最適な高級感あるデザインです。
サムネイル下配置（横型）	メイン画像の下部にサムネイルが横一列スクロールで並びます。AmazonなどECモールの王道スタイルで親しみやすい構成です。
インスタグラム風グリッド配置	メイン画像と複数サムネイルがタイル状に一括配置されます。写真集・カタログ風の視覚的な訴求に向いています。
タッチスライダー（スワイプ対応）	全画面対応のスワイプスライダーで表示します。モバイルファーストなショップやファストファッションに最適です。

2. デザイン・サイズ調整

アクティブ枠線のカラー (HEX): 選択中のサムネイル枠線色をカラーピッカーまたはHEXコード（例: #2563eb）で指定。ショップのブランドカラーに統一できます。
メイン表示エリアの高さ: メイン画像・動画を表示する縦サイズ（標準: 520px など）を選択・調整します。
SNSシェアボタンの位置: メイン画像エリア上の配置位置（右上・左上など）をレイアウトに合わせて指定可能です。

3. 機能ON/OFF設定

ホバーズーム（拡大鏡）機能: 有効にすると、PCでマウスを重ねた際に虫眼鏡ズームレンズが出現します。
ライトボックス拡大表示: メディアクリック時に画面全体へモーダルポップアップ表示するかどうかを設定します。
SNSシェアボタン: メイン画像上にシェアボタン（X, Facebook, LINE, メール, リンクコピー）を表示するかどうかを切り替えます。
EC-CUBE標準「商品画像」との結合表示: 従来の商品画像をギャラリー末尾に自動結合して表示するか、本プラグインの登録メディアのみを表示するかを選択できます。

4. 商品編集画面でのメディア管理

管理画面 → 商品管理 → 商品登録・商品編集 を開くと、画面内に「メディアギャラリー管理（画像・動画・YouTube・Vimeo）」エリアが自動的に表示されます。

1. YouTube / Vimeo 動画の追加

「YouTube / Vimeo 動画をURL追加」入力欄に対象動画のURLを貼り付け、「＋動画を追加」ボタンをクリックします。

YouTube: 通常動画URL（https://www.youtube.com/watch?v=...）および YouTube Shorts（https://www.youtube.com/shorts/...）の両方に対応。
Vimeo: Vimeo動画URL（https://vimeo.com/...）に対応。
※URLを追加すると、動画のサムネイル画像が自動的に取得されてメディアカードが作成されます。

2. 画像・動画ファイルのアップロード

ドラッグ＆ドロップ対応: アップロードエリアに対象ファイルを直接ドラッグ＆ドロップするか、「ファイルを選択」から複数ファイル（画像・動画）を一括選択してアップロードします。
対応画像フォーマット: JPG, PNG, GIF, WebP
対応動画フォーマット: MP4, WebM（HTML5 Canvasによりポスター用サムネイルを自動生成）

3. ドラッグ＆ドロップ並び替えとSEO編集

表示順の変更: 登録されたメディアカードをマウスでドラッグ＆ドロップして並び替えられます。先頭（1番目）のカードが商品詳細ページのメイン表示メディアとなります。
ALT / タイトル個別設定 (✏️ アイコン): 各カードの鉛筆アイコンをクリックするとモーダルが開き、検索エンジン向けの「ALTテキスト」と「タイトル」を個別に設定できます。
メディア削除 (✖ アイコン): 不要になったメディアカードは即座に削除可能です。

5. 共有メディアライブラリの活用

過去に他商品で登録した画像・動画・YouTube・Vimeo素材を、ショップ全体で再利用できる「共有メディアライブラリ」機能を搭載しています。

「📁 メディアライブラリから選択」をクリック

商品編集画面のメディア管理エリア右上にある「📁 メディアライブラリから選択」ボタンをクリックしてモーダルを開きます。

リアルタイム検索で目的の素材を探す

上部の検索バーに「ファイル名」「タイトル」「ALTテキスト」「元商品名」を入力すると、瞬時に候補が絞り込まれます。

複数選択してワンクリックインポート

追加したいメディアカードをクリックしてチェックを入れ（複数選択可）、右下の「＋選択したメディアを追加」をクリックするだけで、現在の商品へ瞬時に追加されます。

💡 サーバー容量0バイト消費 (Zero File Duplication)

メディアライブラリからの追加は実ファイルを二重生成せず同一ファイルを参照するため、サーバーのディスク容量を圧迫することなく安全かつ高速に素材を使い回せます。

6. フロントエンド機能 (拡大鏡・スワイプ)

商品詳細ページでは、購買意欲を高めるためのリッチなインタラクションが自動で有効になります。

1. Hover Magnifier Zoom (3D 拡大鏡レンズ)

PCデスクトップ上でメイン画像にマウスを乗せると、2.5倍の高精細なガラスレンズが出現。60fpsの滑らかな追従で商品の縫製、素材感、細かな仕様を直感的に確認できます。

2. モバイルタッチスワイプ操作

スマートフォン実機での閲覧時には、指先のスワイプ操作で快適に次のメディアへ切り替えられます。端に達した際のスプリングバウンスエフェクトも備えています。

3. フルスクリーン Lightbox & キャプション

画像や動画をクリックすると画面全体が暗転し、高解像度のライトボックスモーダルが展開します。管理画面で設定したタイトルやALTテキストは下部に洗練されたグラスモフィズムバッジとして表示されます。

4. 5種類のSNSシェア機能

メインビューアー右上のシェアボタンから、X（旧Twitter）、Facebook、LINE、メール、URLコピーがワンタップで行えます。

7. SEO構造化データ (Schema.org JSON-LD)

商品詳細ページのHTMLヘッダー内に、Google検索エンジンが推奨する Schema.org 構造化データ（JSON-LD） を自動生成して出力します。

構造化タイプ	対象メディア	SEO上の効果
`ImageObject`	登録画像（JPG / PNG / WebP）	Google画像検索での上位表示およびリッチスニペット表示を促進。
`VideoObject`	MP4動画 / YouTube / Vimeo	Google検索結果および動画検索タブにサムネイル・動画情報がリッチリザルトとして表示。

8. 商品複製（コピー）連動

EC-CUBE標準機能である「商品を複製」を実行した際、元商品に登録されていたメディアギャラリー情報（画像ファイル、アップロード動画、YouTube/Vimeo埋め込みURL、ALTテキスト、タイトル、並び順）もすべて自動的に新商品へ複製・引き継ぎされます。

カラーバリエーションやシリーズ商品の新規登録時でも、メディアを最初から再登録する手間が一切不要です。

9. よくある質問・トラブルシューティング

Q. 動画ファイルのアップロードでエラーが発生する

サーバー（php.ini）のアップロード上限設定（upload_max_filesize および post_max_size）をご確認ください。大容量のMP4動画（例: 20MB以上）をアップロードする場合は、サーバー設定の引き上げを行うか、YouTube / Vimeo へのアップロード後にURL登録することをおすすめします。

Q. YouTube Shorts のURLは登録できますか？

はい、対応しています。「https://www.youtube.com/shorts/xxxx」形式の短尺動画URLをそのまま貼り付けるだけで、自動的にサムネイルを取得してギャラリーに埋め込まれます。

Q. 既存のEC-CUBE標準画像はどうなりますか？

「メディアギャラリー設定」の「EC-CUBE標準『商品画像』との結合表示」にて「結合してギャラリー末尾に表示する」を選択すると、従来アップロードされた標準画像もギャラリー内に自動統合されます。

Q. カスタムデザインの独自テンプレートにも対応していますか？

本プラグインはEC-CUBEの標準フックポイント（EventSubscriber）経由で安全に自動挿入されます。独自レイアウトで表示位置を細かくカスタマイズしたい場合でも、Twigテンプレート内の記述を微調整するだけで柔軟に対応可能です。

10. サポート・ライセンス

本プラグインに関するご質問、カスタマイズのご要望、不具合のご報告がございましたら、EC-CUBEオーナーズストアのお問い合わせ窓口または開発元（CubeLab）までお気軽にお問い合わせください。

※ YouTube / Vimeo のAPI仕様変更やEC-CUBE本体のバージョンアップに伴う機能更新については、随時アップデートにて対応を予定しております。