sct_developer_notifyフックマニュアル

Send Chat Toolsはv1.3.0でsct_developer_notifyを公開しました。

WordPressテーマ、プラグイン製作者がSend Chat Toolsユーザーにアップデートメッセージを送付する事が可能です。

sct_developer_notifyの仕様

フック名	sct_developer_notify
コード	apply_filters( 'sct_developer_notify', $developer_message )

sct_developer_notifyは$developer_messageを引数に送付したいメッセージを設定して利用します。

$developer_messageの仕様

$developer_messageは連想配列形式で設定する必要があります。

引数で受け取った$developer_messageの中に更に配列を追加します。

// $developer_messageのイメージ
$developer_message = [
    [
        'key'     => string,
        'type'    => string,
        'title'   => string,
        'message' => array,
        'url'     => array,
    ],
    [ '他のデベロッパーのメッセージ' ],
    [ '他のデベロッパーのメッセージ' ],
];

$developer_messageに一次元配列として直接keyやtypeといったKeyValueを追加するのではなく、必ず配列を追加する必要がある点に注意してください。

追加する配列の中には以下のキーが必須です。

• key
• type
• title
• message
• url

これ以外のキーが設定されていた場合、安全のためunsetや無視するのではなくチェック段階で失敗しメッセージは送信されません。

key、type、titleはstring、messageとurlはarrayです。

urlはメッセージ中にURLを設定しない場合に限りwebsiteとupdate_pageにnullを受け付けます。

具体的な値は以下に示す通りです。

$developer_message = [
    'key'     => 'my-plugin/my-plugin.php',
    'type'    => 'plugin',
    'title'   => 'My Plugin',
    'message' => [
        'バージョン1.1にアップデートしました。',
        '主な変更点は以下の通りです。',
        '',
        'WordPress5.9に対応',
    ],
    'url'     => [
        'website'     => 'https://www.braveryk7.com/portfolio/send-chat-tools/',
        'update_page' => 'https://www.braveryk7.com/portfolio/send-chat-tools/#update',
    ]
];

key

keyは以下のいずれかを指定してください。

key	詳細	例
テーマ	テーマのslug _site_transient_theme_rootsのkey	my-plugin
プラグイン	プラグインディレクトリ+ファイル active_pluginsのvalue	my-plugin/my-plugin.php

// テーマの場合
// 通常テーマのディレクトリ名、例えばTwentyTwentyOneなら「twentytwentyone」
'key' => 'my-plugin',

// プラグインの場合
// 通常my-plugin/my-plugin.phpにおいてplugin_basename( __FILE__ );で取得できる値
'key' => 'my-plugin/my-plugin.php',

スパム防止のため、テーマやプラグインがユーザーによってWordPressにインストールされているかどうかのチェックを行っています。

wp_optionsカラムからテーマは_site_transient_theme_roots、プラグインはactive_pluginsの中にそれぞれ指定された値が存在しない場合送信されません。

type

typeはtheme、もしくはpluginを指定してください。

それ以外の値が設定されていた場合、メッセージは送信されません。

// テーマの場合
'type' => 'theme',

// プラグインの場合
'type' => 'plugin',

title

titleは送付するメッセージのタイトル部分に挿入されます。

'title' => 'My Plugin',

通常テーマ名、プラグイン名を指定します。

日本語メッセージ例：xxxxxxxxxxから更新のお知らせ

英語メッセージ例：Update notifications from xxxxxxxxxx

message

messageは配列で一行ずつ記述してください。

'message' => [
        'バージョン1.1にアップデートしました。',
        '主な変更点は以下の通りです。',
        '',
        'WordPress5.9に対応',
],

行間のスペースを開けたい場合は空文字（''）を挿入してください。

メッセージ内容は全てエスケープされるのでHTMLコード等を含めることはできません（全て文字列として出力されます）。

また、送信できる最大行数は50行に制限されています。

'message' => [
        __( 'バージョン1.1にアップデートしました。', 'my-plugin' ),
        __( '主な変更点は以下の通りです。', 'my-plugin' ),
        '',
        __( 'WordPress5.9に対応', 'my-plugin' ),
],

i18n対応を行う場合は翻訳関数を利用することもできます。

この場合は翻訳ファイルの用意、または公式ディレクトリ上で翻訳設定を済ませておいてください。

url

urlは配列、またはnullを記述します。

// urlを利用する場合
'url' => [
    'website'     => 'https://www.braveryk7.com/portfolio/send-chat-tools/',
    'update_page' => 'https://www.braveryk7.com/portfolio/send-chat-tools/#update',
]

// urlを利用しない場合
'url' => [
    'website'     => null,
    'update_page' => null,
]

キー
website	公式ウェブサイトのURL
update_page	更新の詳細が記載されているURL

キーは必ずwebiste、update_pageを使用してください、それ以外のキーが設定されていた場合送信されません。

正しい配列を設定された場合、以下のようにURLが出力されます。

公式ウェブサイト: https://www.braveryk7.com/portfolio/send-chat-tools/
アップデート詳細: https://www.braveryk7.com/portfolio/send-chat-tools/#update

URL出力が不要な場合はnullを設定します。

sct_developer_notifyの具体的な使用例

以下にsct_developer_notifyの使用例を示します。

function my_plugin_update_developer_message( $developer_message ) {
    $version = '1.1';

    // 必ずclass_existsを使用してSct_Developer_Notifyの存在を確認する
    if ( class_exists( 'Sct_Developer_Notify' ) ) {
        // my_plugin_versionには'1.0'が保存されている想定
        // バージョンが違った場合にのみメッセージを送信する
        if ( $version !== get_option( 'my_plugin_version' ) ) {
            // 配列である$developer_messageに新たに配列を加えている点に注意
            // × $developer_message =
            // ○ $developer_message[] =
            $developer_message[] = [
                'key'     => 'my-plugin/my-plugin.php',
                'type'    => 'plugin',
                'title'   => 'My Plugin',
                'message' => [
                    'バージョン1.1にアップデートしました。',
                    '主な変更点は以下の通りです。',
                    '',
                    'WordPress5.9に対応',
                ],
                'url'     => [
                    'website'     => 'https://www.braveryk7.com/portfolio/send-chat-tools/',
                    'update_page' => 'https://www.braveryk7.com/portfolio/send-chat-tools/#update',
                ],
            ];

            // 必ずバージョンをwp_optionsにアップデートしてメッセージの無限送信を防ぐ
            update_option( 'my_plugin_version', $version );
        }
    }
    // 必ず引数$developer_messageをreturnする
    return $developer_message;
}

add_filter( 'sct_developer_notify', 'my_plugin_update_developer_message' );

add_filterを使ってフックして使用します。

バージョンを管理して無限送信を防ぐ

必ずwp_optionsに専用のバージョン管理カラムを設定して、メッセージの無限送信を防いでください。

バージョンアップの時に1度だけ送信することを想定しており、何度も送信されてしまうとユーザーにスパムと認識されてしまいます。

あまりにも激しいスパム行為が報告された場合は当該テーマ、プラグインからの利用をSend Chat Tools側でブロックします。

また、次回のアップデートでユーザー自身が特定のテーマ、プラグインからの送付をブロックする機能を追加する予定です。

開発段階でアップデート時に間違いなく1度だけ送信されることを確認してください。

不安な場合はお問い合わせ頂ければ私の方で問題ないか確認します。